sbuilder-mcp 0.30.1 → 0.32.0

package/CHANGELOG.md

@@ -6,6 +6,21 @@ 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.32.0] - 2026-09-11
+
+### Added
+- sb_api_find's call sheet for any `/apps` or `/builtin-apps` operation now explains how to place an installed app's block on a page: build `specials.appBlockRef` as `"<installId>/<blockKey>"` from a row of `GET /api/sites/{siteId}/apps/blocks` and add it with sb_add, which was previously reachable only in the platform's Go source.
+- The same call sheet names the two silent traps around a placed block: never author `specials.appBlockId` or `appBlockHash` (the server's own composition stamps), and an edit made inside a composed block's subtree is stored nowhere.
+- The call sheet also explains installing an app: a built-in app installs with `POST /api/sites/{siteId}/builtin-apps/{key}`, while a marketplace app requires a merchant to approve an OAuth consent screen and cannot be installed through this server.
+
+### Fixed
+- The `key` parameter on the built-in app install and list operations now documents all eight installable keys (mail, multilingual, agent, chat, booking, loyalty, payments, courses) instead of only the first two ever shipped.
+
+## [0.31.0] - 2026-09-11
+
+### Added
+- sb_import and sb_import_site now turn a set of panels with a button row into a real `tab` element instead of flattening it, as long as every panel's label can be read off the page (via `aria-controls`, a shared `data-*` pairing, or position when the button row's clickable count matches the panel count); a panel set whose labels are filled in by script rather than present in the DOM is reported as `panel-set-without-labels` and left flattened rather than guessed at.
+
 ## [0.30.1] - 2026-09-11
 
 ### Changed

package/CHANGELOG.vi.md

@@ -6,6 +6,21 @@ 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.32.0] - 2026-09-11
+
+### Added
+- Call sheet của sb_api_find cho mọi operation `/apps` hoặc `/builtin-apps` giờ giải thích cách đặt block của một app đã cài lên trang: dựng `specials.appBlockRef` dạng `"<installId>/<blockKey>"` từ một dòng của `GET /api/sites/{siteId}/apps/blocks` rồi thêm bằng sb_add — điều trước đây chỉ có thể biết được qua mã nguồn Go của nền tảng.
+- Cùng call sheet đó nêu rõ hai cái bẫy âm thầm quanh một block đã đặt: không bao giờ tự viết `specials.appBlockId` hay `appBlockHash` (đây là các dấu server tự gắn khi compose), và một chỉnh sửa bên trong subtree đã compose sẽ không được lưu ở đâu cả.
+- Call sheet cũng giải thích cách cài app: một app tích hợp sẵn cài bằng `POST /api/sites/{siteId}/builtin-apps/{key}`, còn một app từ marketplace cần merchant tự duyệt màn hình xác nhận OAuth và không thể cài qua server này.
+
+### Fixed
+- Tham số `key` trên các operation cài và liệt kê app tích hợp sẵn giờ ghi đủ tám key có thể cài (mail, multilingual, agent, chat, booking, loyalty, payments, courses) thay vì chỉ hai key đầu tiên từng có.
+
+## [0.31.0] - 2026-09-11
+
+### Added
+- sb_import và sb_import_site giờ biến một bộ panel có hàng nút thành một element `tab` thật thay vì làm phẳng nó, miễn là nhãn của mọi panel đọc được trên trang (qua `aria-controls`, một cặp giá trị `data-*` chung, hoặc theo vị trí khi số phần tử bấm được trong hàng nút khớp với số panel); một bộ panel có nhãn do script điền vào chứ không có sẵn trong DOM sẽ được báo là `panel-set-without-labels` và giữ nguyên dạng làm phẳng thay vì bị đoán mò.
+
 ## [0.30.1] - 2026-09-11
 
 ### Changed

package/dist/catalog/api.generated.js

@@ -3971,7 +3971,7 @@ export const API_OPERATIONS = [
                 "in": "path",
                 "required": true,
                 "type": "string",
-                "description": "App key (mail | multilingual)"
+                "description": "App key: mail | multilingual | agent | chat | booking | loyalty | payments | courses"
             }
         ],
         "bodyDescribed": false,
@@ -3999,7 +3999,7 @@ export const API_OPERATIONS = [
                 "in": "path",
                 "required": true,
                 "type": "string",
-                "description": "App key (mail | multilingual)"
+                "description": "App key: mail | multilingual | agent | chat | booking | loyalty | payments | courses"
             }
         ],
         "bodyDescribed": false,

package/dist/catalog/search.js

@@ -91,6 +91,34 @@ export function describeOperation(op) {
     if (/\/translations(\/|$)/.test(op.path)) {
         out.translation_fields = translationCallSheet();
     }
+    // AN APP'S BLOCKS WERE REACHABLE AND UNUSABLE, because the one thing needed to
+    // place one is a string format that exists only in Go. `page/appblocks.go`
+    // spells it out — SpecAppBlockRef is "<installId>/<blockKey>" — and every
+    // field to build it comes back from `/apps/blocks` (`installId`, `key`). An
+    // agent had the list of blocks, the route that returns it, and no way to turn
+    // a row into a node.
+    //
+    // Attached to the call sheet for the same reason the translation table is:
+    // that is where the agent already is when it decides what to send. No new
+    // tool — placing one is `sb_add`, which already takes the specials it needs.
+    if (/\/(apps|builtin-apps)(\/|$)/.test(op.path)) {
+        out.app_blocks = {
+            place: 'A block from an installed app goes on a page as ONE node carrying ' +
+                'specials.appBlockRef = "<installId>/<blockKey>" — both fields come back from ' +
+                'GET /api/sites/{siteId}/apps/blocks. Add it with sb_add; the platform composes the ' +
+                "app's markup underneath on read.",
+            never: 'Never author specials.appBlockId or appBlockHash. Those are the stamps the SERVER ' +
+                'writes when it composes, and writing one makes the next save decompose your node over ' +
+                'the app instead.',
+            interior: 'An edit INSIDE a composed block is stored nowhere and reported nowhere — the save ' +
+                'reduces the subtree back to the reference. Configure the block through its own ' +
+                'props/slots, never by editing what it rendered.',
+            installing: 'A BUILT-IN app installs with POST /api/sites/{siteId}/builtin-apps/{key} and that key ' +
+                "parameter's description names every installable one. A MARKETPLACE app cannot be " +
+                'installed from here at all: it goes through an OAuth consent screen a person has to ' +
+                'approve, so ask the merchant to install it and then read /apps/blocks again.',
+        };
+    }
     const shape = REQUEST_SHAPES[op.id];
     if (shape) {
         out.body_shape = shape;

package/dist/domains/site/importmap.js

@@ -167,6 +167,29 @@ function one(c, t) {
                 children: body,
             };
         }
+        case 'tab': {
+            const items = (c.children ?? [])
+                .map((item) => one(item, t))
+                .filter((n) => n !== null);
+            // Two is the floor for a tab: one panel with a button over it is a
+            // heading the visitor cannot dismiss.
+            if (items.length < 2)
+                return null;
+            return { type: 'tab', children: items };
+        }
+        case 'tab-item': {
+            const label = c.text?.trim();
+            const body = (c.children ?? [])
+                .map((k) => one(k, t))
+                .filter((n) => n !== null);
+            // NO LABEL, NO PANEL — and this is stricter than the accordion beside it
+            // on purpose. `accordion-content` seeds its own summary, so an unlabelled
+            // one still opens; `tab` builds its BUTTON ROW from these labels, so an
+            // unlabelled panel is one the visitor has no way to reach.
+            if (!label || !body.length)
+                return null;
+            return { type: 'tab-content', specials: { label }, children: body };
+        }
         case 'divider': {
             return { type: 'divider', style: { width: '100%' } };
         }

package/dist/vision/capture.js

@@ -211,6 +211,21 @@ function capturePage(limits) {
             }
             if (!hidden.length)
                 continue;
+            // STAMPED WHILE WE STILL KNOW. Once revealed, a panel is indistinguishable
+            // from an ordinary visible child, so the split is recorded here — and
+            // ONLY the ones that were actually hidden. A first version stamped every
+            // child that shared a tag with a visible peer, which swept in the BUTTON
+            // ROW itself: it is a `<div>` with children like the panels are, so the
+            // tab came out with its own controls as one of its panes.
+            let stamped = 0;
+            for (const k of hidden) {
+                if (!shownByTag[k.tagName] || k.children.length === 0)
+                    continue;
+                k.setAttribute('data-sb-panel', '');
+                stamped += 1;
+            }
+            if (stamped >= 1)
+                parent.setAttribute('data-sb-panelset', '');
             for (const k of hidden) {
                 // Real content only — an empty slot or a script-filled placeholder is
                 // not a panel worth showing, and revealing it costs a skip either way.
@@ -458,6 +473,116 @@ function capturePage(limits) {
                 skip('hidden');
                 return [];
             }
+            // A TAB SET, WHEN — AND ONLY WHEN — ITS LABELS CAN BE READ.
+            //
+            // The platform's `tab` synthesizes its whole button row from each
+            // `tab-content` child's `specials.label` (render/nodes/tab/html.go), so a
+            // tab with no labels is a stack of panels wearing a control nobody can
+            // use. That makes "are there labels" the right question AND the right
+            // discriminator: MEASURED on ttgshop.vn, the panel-set stamp also lands on
+            // a `grid-cols-5` product grid that happens to hide one card, and a label
+            // row is exactly what that grid does not have.
+            //
+            // Three pairings, strongest first, because a wrong label is worse than
+            // none — it puts one collection's name over another's products:
+            //   1. ARIA. `[role=tab][aria-controls=<panel id>]` says it outright.
+            //   2. A SHARED data-* VALUE. `<button data-id="7">` beside
+            //      `<div data-id="7">` is how most hand-rolled tab scripts wire
+            //      themselves, and it survives reordering.
+            //   3. POSITION, and only from a row that holds exactly as many
+            //      clickable items as there are panels — anything else is a guess
+            //      dressed as a match.
+            //
+            // Every panel must come out with a label or this is not a tab. ttgshop.vn
+            // itself does NOT become one: its tab buttons are empty in the DOM and
+            // filled by script, and its section titles are images. Deriving a label
+            // from the `data-url` slug was available and refused — "hot-sale" is not
+            // what the page says, and a Vietnamese slug comes back stripped of its
+            // diacritics, which is the invented-copy defect this repo reports on
+            // everybody else's seeds.
+            const tabSetOf = (host) => {
+                const kids = Array.from(host.children);
+                const revealed = kids.filter((c) => c.getAttribute('data-sb-panel') !== null);
+                if (revealed.length === 0)
+                    return null;
+                // THE BUTTON ROW IS A SIBLING OF THE PANELS, and it has to be taken out
+                // of the set before anything is counted — it is a container of the same
+                // shape, and leaving it in makes the panel count wrong and the pairing
+                // meaningless. It is the child that holds the clickable words.
+                // INNERMOST ONLY. `<li><button>Một</button></li>` is the ordinary way a
+                // tab bar is written, and counting both gives four clickables for two
+                // panels — which fails the count test that position pairing depends on,
+                // so a perfectly labelled tab bar read as unlabelled.
+                const clicksIn = (c) => {
+                    const all = Array.from(c.querySelectorAll('button, a, li, [role="tab"]')).filter((b) => clean(b.textContent).length > 0);
+                    return all.filter((b) => !all.some((o) => o !== b && b.contains(o)));
+                };
+                let bar = null;
+                for (const c of kids) {
+                    if (c.getAttribute('data-sb-panel') !== null)
+                        continue;
+                    if (clicksIn(c).length >= 2) {
+                        bar = c;
+                        break;
+                    }
+                }
+                const tagOf = revealed[0].tagName;
+                const panels = kids.filter((c) => c !== bar && c.tagName === tagOf && c.children.length > 0);
+                if (panels.length < 2)
+                    return null;
+                const clickable = bar ? clicksIn(bar) : [];
+                const labels = [];
+                for (let i = 0; i < panels.length; i += 1) {
+                    const panel = panels[i];
+                    const id = panel.getAttribute('id');
+                    let label = '';
+                    if (id) {
+                        for (const b of Array.from(host.querySelectorAll(`[aria-controls="${id}"]`))) {
+                            const t = clean(b.textContent);
+                            if (t) {
+                                label = t;
+                                break;
+                            }
+                        }
+                    }
+                    if (!label) {
+                        for (const attr of Array.from(panel.attributes ?? [])) {
+                            if (attr.name.indexOf('data-') !== 0 || attr.name === 'data-sb-panel' || !attr.value)
+                                continue;
+                            for (const b of clickable) {
+                                if (b.getAttribute(attr.name) === attr.value) {
+                                    label = clean(b.textContent);
+                                    break;
+                                }
+                            }
+                            if (label)
+                                break;
+                        }
+                    }
+                    if (!label && clickable.length === panels.length)
+                        label = clean(clickable[i].textContent);
+                    if (!label)
+                        return null;
+                    labels.push(label);
+                }
+                const children = [];
+                for (let i = 0; i < panels.length; i += 1) {
+                    const body = walk(panels[i]);
+                    if (body.length === 0)
+                        continue;
+                    children.push({ kind: 'tab-item', text: labels[i], children: body });
+                }
+                if (children.length < 2)
+                    return null;
+                taken.nodes++;
+                return { kind: 'tab', children };
+            };
+            if (el.getAttribute('data-sb-panelset') !== null) {
+                const asTabs = tabSetOf(el);
+                if (asTabs)
+                    return [asTabs];
+                skip('panel-set-without-labels');
+            }
             if (tag === 'DETAILS') {
                 const kids2 = Array.from(el.children);
                 const summary = kids2.filter((c) => c.tagName === 'SUMMARY')[0];

package/package.json

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