sbuilder-mcp 0.1.5 → 0.2.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.2.0] - 2026-09-07
+
+### Added
+- sb_review reports static_in_dataset when an element inside a repeater (such as a plain image in a product card) can only render one authored value across every record, and names the record-capable element to swap in instead.
+- sb_review reports unbound_dataset_element when a dataset element capable of showing a record carries no binding at all, instead of silently rendering the same authored content on every row.
+- sb_page_open reports blank_page_repair when a page's stored document names its root under rootId instead of root_node_id, the alias that renders as an empty page.
+
+### Fixed
+- Opening a page whose document names its root under rootId no longer fails as a damaged document; the document adopts the alias so the next save writes the canonical key and the page stops rendering blank.
+
 ## [0.1.5] - 2026-09-07
 
 ### 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.2.0] - 2026-09-07
+
+### Added
+- sb_review giờ báo cáo static_in_dataset khi một element bên trong repeater (như một image thường trong thẻ sản phẩm) chỉ có thể render một giá trị đã gán cho mọi record, đồng thời chỉ ra element có thể hiển thị record để thay thế.
+- sb_review giờ báo cáo unbound_dataset_element khi một dataset element có khả năng hiển thị record nhưng không mang binding nào, thay vì âm thầm render cùng một nội dung đã gán cho mọi dòng.
+- sb_page_open giờ báo cáo blank_page_repair khi document lưu trữ của trang đặt tên root là rootId thay vì root_node_id — alias khiến trang render rỗng.
+
+### Fixed
+- Mở một trang có document đặt tên root là rootId không còn bị từ chối như document hỏng; document giờ tự nhận alias này để lần lưu kế tiếp ghi đúng khóa chuẩn và trang không còn render rỗng.
+
 ## [0.1.5] - 2026-09-07
 
 ### Added

package/README.md

@@ -87,7 +87,7 @@ make, because those mean "this person's account".
 | `sb_look` | Save, render, and return screenshots plus measured node boxes and layout defects measured on the render |
 | `sb_bind` | Bind a node's content to real store data |
 
-Twenty-five tools, **412 API operations**, 106 elements, 26 binding sources. `sb_api_find`
+Twenty-five tools, **412 API operations**, 106 elements, 77 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

@@ -84,7 +84,7 @@ là "tài khoản của người này".
 | `sb_look` | Lưu, render, trả về ảnh chụp kèm box đo được của node và lỗi bố cục đo trên bản render |
 | `sb_bind` | Gắn nội dung một node vào dữ liệu cửa hàng thật |
 
-Hai mươi lăm tool, **412 operation API**, 106 element, 26 nguồn binding. `sb_api_find` là
+Hai mươi lăm tool, **412 operation API**, 106 element, 77 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/elements.generated.js

@@ -31590,6 +31590,45 @@ export const BINDING_SOURCES = [
     "site.tiktok",
     "site.youtube"
 ];
+export const BOUND_SPECIALS = {
+    "collection-media": [
+        "boundImage"
+    ],
+    "dataset-block": [
+        "boundHref",
+        "boundHrefLabel"
+    ],
+    "media-dataset": [
+        "boundImage",
+        "boundImages"
+    ],
+    "pricing-dataset": [
+        "boundCompare",
+        "boundCompareCents",
+        "boundMoneyOverride",
+        "boundPrice",
+        "boundPriceCents"
+    ],
+    "product-image-feature": [
+        "boundImage",
+        "boundImages",
+        "boundProductURL"
+    ],
+    "product-image-list": [
+        "boundImages"
+    ],
+    "product-variants": [
+        "boundAttributes",
+        "boundVariations"
+    ],
+    "qr-code": [
+        "boundValue"
+    ],
+    "text-dataset": [
+        "boundHtml",
+        "boundText"
+    ]
+};
 export const TRAIT_WRITES = {
     "font_size": {
         "key": "font_size",

package/dist/domains/site/document.js

@@ -51,13 +51,48 @@ export class PageDoc {
             if (!d.schema_version)
                 d.schema_version = 2;
         }
+        // A DOCUMENT THAT NAMES ITS ROOT UNDER THE WRONG KEY.
+        //
+        // `rootId` is the key an APP BLOCK and a section template use for the same
+        // idea (server/internal/apps/blocks.go), so a document assembled from that
+        // shape and PUT to a page carries it. The page renderer reads only
+        // `root_node_id`: it finds no root, walks nothing, and publishes a page that
+        // answers 200 with an EMPTY BODY. Found in the wild on a live storefront's
+        // order-complete page, where the shopper who had just paid saw a blank
+        // screen.
+        //
+        // Adopted rather than refused, because refusing left the one tool that can
+        // SEE the problem unable to open the page, and the repair is a single save:
+        // the canonical key is written and the alias dropped from what this holds.
+        let adopted;
+        if (!d.root_node_id || !d.nodes[d.root_node_id]) {
+            const bag = d;
+            for (const key of ['rootId', 'rootNodeId']) {
+                const value = bag[key];
+                if (typeof value === 'string' && d.nodes[value]) {
+                    d.root_node_id = value;
+                    delete bag[key];
+                    adopted = key;
+                    break;
+                }
+            }
+        }
         if (!d.root_node_id || !d.nodes[d.root_node_id]) {
             throw new Error(`sbuilder: document is damaged — root_node_id=${JSON.stringify(d.root_node_id)} names no ` +
                 `node, but ${Object.keys(d.nodes).length} nodes are present. Open the page in the ` +
                 'editor once; its hydrate path repairs this.');
         }
-        return new PageDoc(d);
+        const out = new PageDoc(d);
+        out.adoptedRootKey = adopted;
+        return out;
     }
+    /**
+     * The wrong key this document named its root under, when it did.
+     *
+     * Set means the page currently PUBLISHES BLANK and the next save fixes it —
+     * a fact no other surface reports, so the tool layer says it out loud.
+     */
+    adoptedRootKey;
     get rev() {
         return this.revision;
     }

package/dist/domains/site/findings.js

@@ -1,4 +1,6 @@
-import { BINDING_SOURCES } from '../../catalog/elements.generated.js';
+import { BINDING_SOURCES, BOUND_SPECIALS } from '../../catalog/elements.generated.js';
+/** The elements whose renderer reads a bound special — the ones that can show a record. */
+const RECORD_ELEMENTS = Object.keys(BOUND_SPECIALS).sort().join(', ');
 /**
  * One fix per KIND of finding, as a template.
  *
@@ -16,6 +18,13 @@ export const FIX = {
     empty_text: 'Set it: sb_set id "<id>", namespace specials, keys { "<key>": … }.',
     missing_media: 'Set it: sb_set id "<id>", namespace specials, keys { "<key>": … }.',
     placeholder_content: 'Write the real copy: sb_set id "<id>", namespace specials, keys { "<key>": … }.',
+    // The fix is a DIFFERENT ELEMENT, not a value: setting "<key>" here would put
+    // one authored value on every row of the repeater.
+    static_in_dataset: `Swap the element: sb_add one of ${RECORD_ELEMENTS} in the same parent, sb_bind it ` +
+        '(field "specials.bound…", source matching the record), sb_move it into place, then ' +
+        'sb_remove id "<id>". Setting "<key>" on this one would show the same value in every row.',
+    unbound_dataset_element: 'Bind it: sb_bind id "<id>", field "specials.<key>", and the source that names the record ' +
+        'field you want (sb_bind refuses an unknown source and lists every valid one).',
     dead_binding_source: `Rebind with sb_bind using one of: ${BINDING_SOURCES.join(', ')}.`,
     // "<key>" here is documentation, not a placeholder: this template is never
     // filled with a key, so the reader sees the form a field must take.

package/dist/domains/site/review.js

@@ -1,5 +1,5 @@
 import { childrenOf, isOverlay, pageChildren, appBlockRoot } from '../../core/tree.js';
-import { ELEMENTS, BINDING_SOURCES } from '../../catalog/elements.generated.js';
+import { ELEMENTS, BINDING_SOURCES, BOUND_SPECIALS } from '../../catalog/elements.generated.js';
 import { fill } from './findings.js';
 /**
  * Shipped with every non-empty finding list.
@@ -21,6 +21,23 @@ function contentKeys(type) {
 function seededValue(type, key) {
     return (ELEMENTS[type]?.defaults.specials ?? {})[key];
 }
+/**
+ * A container that renders its subtree ONCE PER RECORD.
+ *
+ * `list-dataset` is the repeater and `dataset-block` its per-record template;
+ * both are read off the catalog rather than named here, so a new repeater the
+ * platform ships is covered the day the catalog is regenerated.
+ */
+function repeats(type) {
+    const meta = ELEMENTS[type];
+    return Boolean(meta?.isContainer && meta.category === 'dataset');
+}
+/** The element types that can actually show a record: their renderer reads a bound special. */
+const BOUND_TYPES = Object.keys(BOUND_SPECIALS).sort();
+/** Whether this element type's renderer reads anything a binding can write. */
+function canShowARecord(type) {
+    return (BOUND_SPECIALS[type] ?? []).length > 0;
+}
 /**
  * Everything wrong with this page that a person would notice.
  *
@@ -48,15 +65,22 @@ export function reviewDesign(doc) {
     // Document order, depth-first from ROOT: the order a reader meets them.
     const seen = new Set();
     const walkOrder = [];
-    const go = (id) => {
+    // Which repeater each node sits inside, filled on the way down. A repeater
+    // itself belongs to the scope OUTSIDE it, which is why this is set before the
+    // scope for the children is computed.
+    const inRepeater = new Map();
+    const go = (id, repeater) => {
         if (seen.has(id) || overlayIds.has(id))
             return;
         seen.add(id);
         walkOrder.push(id);
+        if (repeater)
+            inRepeater.set(id, repeater);
         if (appBlockRoot(d, id) === id)
             return;
+        const inner = repeats(d.nodes[id]?.data.type ?? '') ? (repeater ?? id) : repeater;
         for (const k of childrenOf(d, id))
-            go(k);
+            go(k, inner);
     };
     go(d.root_node_id);
     for (const id of walkOrder) {
@@ -86,10 +110,41 @@ export function reviewDesign(doc) {
                 fix: fill('empty_container', { id }),
             });
         }
+        const bindings = n.bindings ?? [];
+        const repeater = inRepeater.get(id);
+        const boundFields = new Set(bindings.map((b) => b.field));
+        /**
+         * Whether a binding, not the author, supplies this key at render time.
+         *
+         * Either the binding names the key outright, or the element is one whose
+         * renderer PREFERS its bound special over the authored one — a bound
+         * `collection-media` with an empty `src` is finished, not unfinished, and
+         * reporting it would be the false positive that teaches a reader to ignore
+         * the list.
+         */
+        const supplied = (key) => boundFields.has(`specials.${key}`) || (bindings.length > 0 && canShowARecord(type));
         for (const key of contentKeys(type)) {
             const value = (n.specials ?? {})[key];
             const seed = seededValue(type, key);
             const isBlank = value === undefined || value === null || String(value).trim() === '';
+            if (supplied(key))
+                continue;
+            // INSIDE A REPEATER the generic advice is actively wrong: setting a static
+            // src on an image in a product card puts the SAME picture on every card and
+            // the product's own photo can never appear. The defect is the element
+            // choice, not the missing value, so it gets its own finding and its own fix.
+            if (repeater && (isBlank || (seed !== undefined && value === seed))) {
+                out.push({
+                    code: 'static_in_dataset',
+                    nodeId: id,
+                    type,
+                    problem: `Inside the repeater "${repeater}", but "${type}" renders only what the document ` +
+                        `authors — so every record shows the same ${key}, and the record's own never appears.`,
+                    key,
+                    fix: fill('static_in_dataset', { id, key }),
+                });
+                continue;
+            }
             if (isBlank) {
                 // An element that seeds a blank (image.src is "") is not misconfigured —
                 // it is unfinished, and it renders as a gap or a broken frame.
@@ -120,11 +175,25 @@ export function reviewDesign(doc) {
                 });
             }
         }
+        // A dataset element with NO binding at all is the same silence from the other
+        // direction: its renderer is waiting for a bound special that nothing writes,
+        // so it falls back to whatever the document authored — once, for every record.
+        if (repeater && canShowARecord(type) && bindings.length === 0) {
+            const key = BOUND_SPECIALS[type][0];
+            out.push({
+                code: 'unbound_dataset_element',
+                nodeId: id,
+                type,
+                problem: `"${type}" reads specials.${key} from a binding and has none, so every row in ` +
+                    `"${repeater}" renders the same authored content.`,
+                key,
+                fix: fill('unbound_dataset_element', { id, key }),
+            });
+        }
         // A binding whose source the renderer does not provide resolves to nothing,
         // and the element falls back to its own placeholder — indistinguishable, on
         // screen, from data that has not loaded.
-        for (const b of n
-            .bindings ?? []) {
+        for (const b of bindings) {
             if (b.source && !BINDING_SOURCES.includes(b.source)) {
                 out.push({
                     code: 'dead_binding_source',

package/dist/tools/page.js

@@ -142,7 +142,20 @@ export function registerPageTools(server, ctx) {
         annotations: { readOnlyHint: true },
     }, async ({ site_id, page_id }) => {
         const outline = await session.open(site_id, page_id);
-        return text({ outline, ...reviewField(ctx, session.current()) });
+        const doc = session.current();
+        // A page whose stored document named its root under the app-block key
+        // renders as an empty <body> and says nothing about why. Nobody else can
+        // see this, so it is reported on open rather than left for the screenshot.
+        const blank_page_repair = doc.adoptedRootKey
+            ? `This page's document names its root as "${doc.adoptedRootKey}", not "root_node_id", so ` +
+                'the renderer finds no root and publishes an EMPTY BODY. The next save from here writes ' +
+                'the canonical key and fixes it; publish afterwards.'
+            : undefined;
+        return text({
+            outline,
+            ...(blank_page_repair ? { blank_page_repair } : {}),
+            ...reviewField(ctx, doc),
+        });
     });
     server.registerTool('sb_outline', {
         description: 'The open page as a compressed tree — id, type, name, child count, band, and whether a ' +

package/package.json

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