sbuilder-mcp 0.85.0 → 0.87.0

package/CHANGELOG.md

@@ -6,6 +6,30 @@ 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.87.0] - 2026-10-12
+
+### Added
+- `sb_review` reports `example_copy` for text, labels and alt text that still carry a built-in layout's example copy, such as "Tiêu đề chính", invented figures, promises and customer quotes.
+- `sb_review` reports `invisible_text` for text whose colour matches its background.
+- `sb_review` reports `demo_variant_options` for a variant picker that shows fallback options instead of the product's own.
+- `sb_review` reports `empty_page` for a page that has only a header and footer.
+- `sb_review` flags product categories without an image as a `categoryImages` readiness gap when the page shows category tiles.
+- `sb_template_use` reports how many elements still carry the layout's example copy.
+- `sb_page_create` reports how many findings a seeded layout skeleton already has, so the placeholder copy and empty slots get filled.
+
+### Changed
+- `sb_api_find` and `sb_api_call` resolve an operation id regardless of letter case, so `{siteID}` and `{siteId}` reach the same route when the match is unique.
+- `sb_import` reads page tokens only from bands on a light ground, so an inverted band such as a call-to-action no longer supplies the page's button fill.
+
+### Fixed
+- `sb_add` on the page root without `index` places the new section before the footer instead of after it, which the band-order check refused to save.
+- `sb_review` no longer reports `off_canvas` findings for a header's closed mobile menu.
+
+## [0.86.0] - 2026-10-12
+
+### Added
+- `sb_api_find` and `sb_api_call` reach 849 platform operations, including the GrabFood delivery app: connecting a site, listing the orders it pushes, and accepting or rejecting them.
+
 ## [0.85.0] - 2026-10-11
 
 ### Added

package/CHANGELOG.vi.md

@@ -6,6 +6,30 @@ 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.87.0] - 2026-10-12
+
+### Added
+- `sb_review` báo `example_copy` cho chữ, nhãn và alt còn mang nội dung mẫu của layout dựng sẵn, như "Tiêu đề chính", số liệu, lời hứa và lời khen khách hàng bịa.
+- `sb_review` báo `invisible_text` cho chữ có màu trùng với nền.
+- `sb_review` báo `demo_variant_options` cho bộ chọn biến thể hiện tuỳ chọn giả thay vì tuỳ chọn của chính sản phẩm.
+- `sb_review` báo `empty_page` cho trang chỉ có header và footer.
+- `sb_review` đánh dấu danh mục sản phẩm chưa có ảnh là thiếu sót `categoryImages` khi trang hiển thị ô danh mục.
+- `sb_template_use` cho biết còn bao nhiêu phần tử mang nội dung mẫu của layout.
+- `sb_page_create` cho biết khung layout vừa tạo đã có bao nhiêu phát hiện, để điền chữ giữ chỗ và các ô trống.
+
+### Changed
+- `sb_api_find` và `sb_api_call` nhận id operation không phân biệt hoa thường, nên `{siteID}` và `{siteId}` cùng tới một route khi khớp là duy nhất.
+- `sb_import` chỉ đọc token của trang từ các dải có nền sáng, nên dải đảo màu như call-to-action không còn quyết định màu nền nút của trang.
+
+### Fixed
+- `sb_add` vào gốc trang khi không có `index` đặt section mới trước footer thay vì sau footer, vị trí mà kiểm tra thứ tự dải từng từ chối lưu.
+- `sb_review` không còn báo `off_canvas` cho menu di động đang đóng trong header.
+
+## [0.86.0] - 2026-10-12
+
+### Added
+- `sb_api_find` và `sb_api_call` truy cập được 849 operation của platform, gồm app giao hàng GrabFood: kết nối site, liệt kê đơn hàng được đẩy về, và nhận hoặc từ chối đơn.
+
 ## [0.85.0] - 2026-10-11
 
 ### Added

package/README.md

@@ -118,7 +118,7 @@ in this client: one would put the very key the platform exists to hold back into
 | `sb_store` | Run a store flow that must happen in a fixed order — `checkout` (the four writes that make a working one), `checkout_sync` (the store's current payment and delivery methods into every existing order form, checkout page republished), `form` (any of the platform's 17 templates with its own field document), `chrome` (one shared header or footer on a real site menu — desktop menu, mobile drawer, cart and account icons), `menu` (a menu node bound to the site's menu, its links resolved), `overlay_attach` (a pop-up or quick view on the open page), `cart` (the site's cart drawer, when it has none; `relocalize` puts an existing one in the site's language) and `app` (a built-in app plus the pages it needs), `global_attach` / `global_detach` (put an EXISTING shared section on the open page, or take it off), `global_promote` (make a section on the page a NEW shared section) and `template_save` (save a section as a reusable template) |
 | `sb_undo` | Undo / redo this session's writes — page and form edits and `sb_api_call` PUTs; a page is refused if someone else saved it since. The platform's versions and history (`sb_page_version`) outlive this process |
 
-Twenty-eight tools, **843 API operations** (309 of the 389 writes carrying a body shape read
+Twenty-eight tools, **849 API operations** (312 of the 393 writes carrying a body shape read
 off the handler), 123 elements, 94 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

package/README.vi.md

@@ -115,7 +115,7 @@ nhét ngược lại vào mọi bản cài.
 | `sb_store` | Chạy một luồng cửa hàng bắt buộc đúng thứ tự — `checkout` (bốn lệnh ghi tạo nên trang thanh toán), `checkout_sync` (đưa phương thức thanh toán và giao hàng hiện tại vào mọi form đặt hàng đã có, publish lại trang thanh toán), `form` (một trong 17 template của nền tảng kèm field document của nó), `chrome` (một header hoặc footer dùng chung trên menu thật của site — menu desktop, drawer mobile, icon giỏ hàng và tài khoản), `menu` (một node menu bind vào menu của site, link đã phân giải), `overlay_attach` (một pop-up hay quick view trên trang đang mở), `cart` (ngăn giỏ hàng của site, khi chưa có; `relocalize` đưa ngăn giỏ đã có về ngôn ngữ của site), `app` (một app dựng sẵn kèm những trang nó cần), và `global_attach` / `global_detach` (đặt một section dùng chung ĐÃ CÓ lên trang đang mở, hoặc gỡ ra), `global_promote` (biến một section trên trang thành section dùng chung MỚI) và `template_save` (lưu một section làm mẫu dùng lại) |
 | `sb_undo` | Hoàn tác / làm lại các thao tác ghi trong phiên — chỉnh sửa trang, form và PUT qua `sb_api_call`; trang bị từ chối nếu người khác đã lưu sau đó. Version và history của nền tảng (`sb_page_version`) sống lâu hơn process này |
 
-Hai mươi tám tool, **843 operation API** (309 trong 389 lệnh ghi có hình dạng body đọc thẳng
+Hai mươi tám tool, **849 operation API** (312 trong 393 lệnh ghi có hình dạng body đọc thẳng
 từ handler), 123 element, 94 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

package/dist/catalog/api.generated.js

@@ -1,7 +1,7 @@
 export const SWAGGER_SOURCE = {
-    "operations": 843,
-    "definitions": 278,
-    "bodyCarrying": 373,
+    "operations": 849,
+    "definitions": 280,
+    "bodyCarrying": 376,
     "bodyUndescribed": 102,
     "generatedFrom": "server/docs/swagger.json"
 };
@@ -781,6 +781,34 @@ export const API_OPERATIONS = [
         "bodyRef": null,
         "credential": "siteScoped"
     },
+    {
+        "id": "post:/_wb/delivery/{app}/{path}",
+        "method": "POST",
+        "path": "/_wb/delivery/{app}/{path}",
+        "tags": [
+            "pos"
+        ],
+        "summary": "Delivery-app partner endpoints (GrabFood)",
+        "params": [
+            {
+                "name": "app",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "App id (grabfood)"
+            },
+            {
+                "name": "path",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "oauth/token | orders | order-state | menu-sync-state"
+            }
+        ],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "siteScoped"
+    },
     {
         "id": "get:/_wb/feed/facets",
         "method": "GET",
@@ -7550,6 +7578,181 @@ export const API_OPERATIONS = [
         "bodyRef": null,
         "credential": "siteScoped"
     },
+    {
+        "id": "get:/api/sites/{siteId}/delivery-apps/orders",
+        "method": "GET",
+        "path": "/api/sites/{siteId}/delivery-apps/orders",
+        "tags": [
+            "pos"
+        ],
+        "summary": "List orders pushed by delivery apps",
+        "params": [
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            },
+            {
+                "name": "state",
+                "in": "query",
+                "required": false,
+                "type": "string",
+                "description": "new|deciding|accepted|rejected|cancelled|completed"
+            },
+            {
+                "name": "limit",
+                "in": "query",
+                "required": false,
+                "type": "integer",
+                "description": "page size"
+            },
+            {
+                "name": "offset",
+                "in": "query",
+                "required": false,
+                "type": "integer",
+                "description": "offset"
+            }
+        ],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "siteScoped"
+    },
+    {
+        "id": "post:/api/sites/{siteId}/delivery-apps/orders/{id}/accept",
+        "method": "POST",
+        "path": "/api/sites/{siteId}/delivery-apps/orders/{id}/accept",
+        "tags": [
+            "pos"
+        ],
+        "summary": "Accept a delivery-app order",
+        "params": [
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            },
+            {
+                "name": "id",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Order ID"
+            }
+        ],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "siteScoped"
+    },
+    {
+        "id": "post:/api/sites/{siteId}/delivery-apps/orders/{id}/reject",
+        "method": "POST",
+        "path": "/api/sites/{siteId}/delivery-apps/orders/{id}/reject",
+        "tags": [
+            "pos"
+        ],
+        "summary": "Reject a delivery-app order",
+        "params": [
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            },
+            {
+                "name": "id",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Order ID"
+            },
+            {
+                "name": "body",
+                "in": "body",
+                "required": true,
+                "type": "object",
+                "description": "{reason}"
+            }
+        ],
+        "bodyDescribed": true,
+        "bodyRef": "internal_deliveryapps_rest.rejectBody",
+        "credential": "siteScoped"
+    },
+    {
+        "id": "get:/api/sites/{siteId}/delivery-apps/{app}/connection",
+        "method": "GET",
+        "path": "/api/sites/{siteId}/delivery-apps/{app}/connection",
+        "tags": [
+            "pos"
+        ],
+        "summary": "Read or replace the site's connection to a delivery app",
+        "params": [
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            },
+            {
+                "name": "app",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "App id (grabfood, shopeefood)"
+            },
+            {
+                "name": "connection",
+                "in": "body",
+                "required": false,
+                "type": "object",
+                "description": "Connection (PUT only)"
+            }
+        ],
+        "bodyDescribed": true,
+        "bodyRef": "internal_deliveryapps_rest.connectionInput",
+        "credential": "siteScoped"
+    },
+    {
+        "id": "put:/api/sites/{siteId}/delivery-apps/{app}/connection",
+        "method": "PUT",
+        "path": "/api/sites/{siteId}/delivery-apps/{app}/connection",
+        "tags": [
+            "pos"
+        ],
+        "summary": "Read or replace the site's connection to a delivery app",
+        "params": [
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            },
+            {
+                "name": "app",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "App id (grabfood, shopeefood)"
+            },
+            {
+                "name": "connection",
+                "in": "body",
+                "required": false,
+                "type": "object",
+                "description": "Connection (PUT only)"
+            }
+        ],
+        "bodyDescribed": true,
+        "bodyRef": "internal_deliveryapps_rest.connectionInput",
+        "credential": "siteScoped"
+    },
     {
         "id": "get:/api/sites/{siteId}/discounts",
         "method": "GET",
@@ -32486,6 +32689,25 @@ export const API_DEFINITIONS = {
             }
         }
     },
+    "internal_deliveryapps_rest.connectionInput": {
+        "type": "object",
+        "properties": {
+            "enabled": {
+                "type": "boolean"
+            },
+            "externalMerchantId": {
+                "type": "string"
+            }
+        }
+    },
+    "internal_deliveryapps_rest.rejectBody": {
+        "type": "object",
+        "properties": {
+            "reason": {
+                "type": "string"
+            }
+        }
+    },
     "internal_discounts_rest.grantRequest": {
         "type": "object",
         "properties": {

package/dist/catalog/deadkeys.generated.js

@@ -1,6 +1,6 @@
 export const DEAD_KEY_SOURCE = {
-    "files": 5665,
-    "identifiers": 103621,
+    "files": 5691,
+    "identifiers": 104085,
     "seededKeys": 445,
     "dead": 0
 };

package/dist/catalog/search.js

@@ -28,7 +28,15 @@ const PRODUCT_WRITE_IDS = new Set([
     'put:/api/v1/products/{id}',
 ]);
 export function findOperation(id) {
-    return API_OPERATIONS.find((o) => o.id === id);
+    const exact = API_OPERATIONS.find((o) => o.id === id);
+    if (exact)
+        return exact;
+    // The platform spells one parameter two ways — `{siteId}` almost everywhere,
+    // `{siteID}` on the menu routes — and a caller (or a readiness fix text) that
+    // learned the common one was told "unknown operation" for one letter. Only a
+    // UNIQUE fold is taken, so two routes differing by case alone stay refused.
+    const folded = API_OPERATIONS.filter((o) => o.id.toLowerCase() === id.toLowerCase());
+    return folded.length === 1 ? folded[0] : undefined;
 }
 export function searchOperations(query, opts = {}) {
     const limit = opts.limit ?? DEFAULT_FIND_LIMIT;

package/dist/catalog/shapes.generated.js

@@ -1,10 +1,10 @@
 export const SHAPE_SOURCE = {
-    "writeOperations": 389,
-    "shaped": 309,
-    "fromHandlers": 299,
+    "writeOperations": 393,
+    "shaped": 312,
+    "fromHandlers": 302,
     "fromSwaggerOnly": 10,
     "withReadOnly": 30,
-    "structsRead": 3194
+    "structsRead": 3226
 };
 export const REQUEST_SHAPES = {
     "post:/api/sites/{id}/ai-credits/purchase": {
@@ -3188,6 +3188,48 @@ export const REQUEST_SHAPES = {
             "updatedAt"
         ]
     },
+    "put:/api/sites/{siteId}/delivery-apps/{app}/connection": {
+        "fields": [
+            {
+                "name": "enabled",
+                "type": "boolean"
+            },
+            {
+                "name": "externalMerchantId",
+                "type": "string"
+            }
+        ],
+        "source": "go",
+        "goType": "connectionInput"
+    },
+    "post:/api/sites/{siteId}/delivery-apps/orders/{id}/reject": {
+        "fields": [
+            {
+                "name": "reason",
+                "type": "string"
+            }
+        ],
+        "source": "go",
+        "goType": "rejectBody"
+    },
+    "post:/_wb/delivery/{app}/{path}": {
+        "fields": [
+            {
+                "name": "client_id",
+                "type": "string"
+            },
+            {
+                "name": "client_secret",
+                "type": "string"
+            },
+            {
+                "name": "grant_type",
+                "type": "string"
+            }
+        ],
+        "source": "go",
+        "goType": "(inline)"
+    },
     "post:/api/sites/{siteId}/discounts": {
         "fields": [
             {

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": "8384af1dd6df12bb80a75a8b53e88c377d3f722c",
-    "committedAt": "2026-10-12T01:13:06+07:00",
+    "commit": "df9accca9c8a0e402ca5520beddcb52c0843f7f5",
+    "committedAt": "2026-10-12T09:14:30+07:00",
     "dirty": false
 };

package/dist/domains/site/examplecopy.js

@@ -0,0 +1,56 @@
+import { LAYOUT_PATTERNS, THEME_TOKENS } from './patterns.js';
+/**
+ * THE BUILT-IN LAYOUTS' EXAMPLE COPY, so a review can tell it was never replaced.
+ *
+ * Measured on a store built end to end with these tools: the home page published
+ * "Tiêu đề chính", "Lợi ích một / Một hoặc hai câu." and, in the hero's picture
+ * slot, the sentence telling the AGENT to run sb_media_upload — all to shoppers —
+ * and sb_review called the page clean, because none of it is an element's own
+ * seed. Worse are the CLAIMS: "1.000+ khách hàng", "4,9/5", "Đổi mới trong 7 ngày",
+ * a testimonial signed "Nguyễn Minh Anh" — published, they are statements about
+ * this shop that nobody made.
+ *
+ * DERIVED by building every pattern, minus the short list of labels that are fine
+ * as they stand. Derived rather than listed so a pattern added or reworded later is
+ * covered on the day it lands: new copy is example copy until someone says it is a
+ * usable label — the safe direction to be wrong in.
+ */
+const USABLE_AS_IS = new Set([
+    'Mua ngay', 'Tìm hiểu thêm', 'Tìm hiểu thêm →', 'Xem tất cả', 'Sản phẩm nổi bật', 'Danh mục sản phẩm',
+    'Bộ sưu tập mới', 'Chào mừng', 'Lợi ích', 'Vì sao chọn chúng tôi', 'Sẵn sàng bắt đầu?', 'Thư viện ảnh',
+    'Hỗ trợ', 'Câu hỏi thường gặp', 'Giao hàng mất bao lâu?', 'Đổi trả thế nào?', 'Thanh toán ra sao?',
+    'Đối tác của chúng tôi', 'Cam kết của chúng tôi', 'Giao hàng nhanh', 'Bảo hành chính hãng',
+    'Đổi trả dễ dàng', 'Thanh toán an toàn', 'Khách hàng nói gì', '★★★★★', 'Cách hoạt động',
+    'Ba bước đơn giản', '01', '02', '03', 'Chọn sản phẩm', 'Đặt hàng', 'Nhận hàng', 'Câu chuyện',
+    'Bảng giá', 'Chọn gói phù hợp', 'Cơ bản', 'Chọn gói', 'Khách hàng', 'Đánh giá trung bình',
+    'Giao trong nội thành', 'Tiêu chuẩn', 'Cao cấp',
+]);
+const TEXT_KEYS = ['text', 'label', 'alt'];
+let cache = null;
+/** Example copy → the id of the layout it came from. Built once per process. */
+export function exampleCopy() {
+    if (cache)
+        return cache;
+    const out = new Map();
+    const walk = (n, id) => {
+        if (!n)
+            return;
+        for (const k of TEXT_KEYS) {
+            const v = n.specials?.[k];
+            if (typeof v === 'string' && v.trim() && !USABLE_AS_IS.has(v) && !out.has(v))
+                out.set(v, id);
+        }
+        for (const c of n.children ?? [])
+            walk(c, id);
+    };
+    for (const p of LAYOUT_PATTERNS) {
+        try {
+            walk(p.build(THEME_TOKENS, []), p.id);
+        }
+        catch {
+            // A pattern that cannot build without a pool contributes nothing here.
+        }
+    }
+    cache = out;
+    return out;
+}

package/dist/domains/site/findings.js

@@ -22,6 +22,13 @@ export const FIX = {
     // this surface EXISTS. An empty state is authored out of sight — it only shows
     // when the list is empty — so an agent that never saw it does not know there is
     // anything to write.
+    demo_variant_options: 'Clear the fallback: sb_set id "<id>", namespace config, keys { "attributes": [] }, base: true. ' +
+        'Products WITH options still show their own (the binding wins); products without show no picker.',
+    invisible_text: 'Give it a colour that reads on its ground: sb_set id "<id>", namespace style, keys { "color": … } ' +
+        '(or unset "color" so the theme decides). For a button, change its fill or its text — not both to the same.',
+    example_copy: 'Write this shop\'s own words: sb_set id "<id>", namespace specials, keys { "<key>": … }. ' +
+        'A figure, a delivery or return promise, or a customer quote must be TRUE for this shop — ' +
+        'if you do not know it, remove the element (sb_remove) rather than guess.',
     default_seed_copy: 'Write it in the shop\'s own language and ink: sb_set id "<id>", namespace specials, ' +
         'keys { "<key>": … }. It is a seeded satellite (an empty state, an element\'s chrome), ' +
         'so it only appears when the list is empty or the control is idle — sb_outline lists it ' +

package/dist/domains/site/importmap.js

@@ -1,4 +1,4 @@
-import { pageChildren, walk } from '../../core/tree.js';
+import { pageChildren } from '../../core/tree.js';
 import { isGlobal } from './traps.js';
 import { stickySeeds } from './sticky.js';
 import { TEXT_STYLE_KEYS } from '../../catalog/elements.generated.js';
@@ -79,9 +79,29 @@ export function tokensFromPage(doc) {
         else if (!block && t === 'flex-block')
             block = n;
     };
+    // NOT FROM A BAND ON A DARK OR COLOURED GROUND. Its type and buttons are
+    // inverted on purpose, so they say nothing about the page's own. Measured: a
+    // hero re-added below an sb_cta_band (primary-green ground, white button with
+    // green text) took that white button as the page's fill — and published a
+    // white "Mua ngay" on the white hero, plus a white eyebrow, both invisible.
+    // By id, not through walk(): its visitor gets the node, and a node is not
+    // guaranteed to carry its own id.
+    const read = (id, onDark, seen) => {
+        const n = doc.nodes[id];
+        if (!n || seen.has(id))
+            return;
+        seen.add(id);
+        const t = n.data.type;
+        const dark = onDark || ((t === 'flex-section' || t === 'flex-block') && !lightGround(styleOf(n).backgroundColor));
+        if (!dark)
+            visit(n);
+        for (const k of n.data.nodes ?? [])
+            read(k, dark, seen);
+    };
+    const seen = new Set();
     for (const id of pageChildren(doc))
         if (!isGlobal(doc, id))
-            walk(doc, id, visit);
+            read(id, false, seen);
     const h = styleOf(heading);
     const p = styleOf(text);
     const b = styleOf(button);
@@ -99,6 +119,32 @@ export function tokensFromPage(doc) {
         ...(str(bl.maxWidth) ? { sectionMaxWidth: str(bl.maxWidth) } : {}),
     };
 }
+/**
+ * Is this a ground ordinary type reads on? Unset, transparent, white, the
+ * theme's own background token, or a literal colour light enough. Anything
+ * else — a dark or saturated literal, another theme var — is treated as an
+ * inverted band, which only ever costs a token read, never a wrong one.
+ */
+function lightGround(bg) {
+    const v = typeof bg === 'string' ? bg.trim().toLowerCase() : '';
+    if (!v || v === 'transparent' || v === 'white' || v === 'var(--wb-color-background)')
+        return true;
+    let rgb = null;
+    const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/.exec(v);
+    if (hex) {
+        const h = hex[1].length === 3 ? hex[1].replace(/./g, (c) => c + c) : hex[1];
+        rgb = [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
+    }
+    else {
+        const m = /^rgba?\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)/.exec(v);
+        if (m)
+            rgb = [m[1], m[2], m[3]].map(Number);
+    }
+    if (!rgb)
+        return false;
+    const [r, g, b] = rgb.map((c) => c / 255);
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b > 0.8;
+}
 /** A heading's tag, clamped to what HTML has. */
 function headingTag(level) {
     const n = Math.min(6, Math.max(1, Math.round(level ?? 2)));

package/dist/domains/site/offscreen.js

@@ -80,8 +80,21 @@ export function offscreenNodes(doc) {
         for (const n of subtreeIds(doc, id))
             out.add(n);
     }
+    // THE MOBILE MENU LIVES INSIDE THE HEADER, legitimately, so the ROOT-only
+    // sweep above never reached it. Measured: a store header from sb_store
+    // action:"chrome" — its closed menu-drawer, parked at x −420 — gave four
+    // off_canvas findings at 390px on every page. Only the menu types: a popup
+    // nested in a section is still a document the platform refuses.
+    for (const [id, n] of Object.entries(doc.nodes)) {
+        if (!NESTED_OFFSCREEN.has(n?.data?.type ?? '') || out.has(id))
+            continue;
+        for (const k of subtreeIds(doc, id))
+            out.add(k);
+    }
     return out;
 }
+/** Overlay types that legitimately sit deep in a tree (a header's mobile menu). */
+const NESTED_OFFSCREEN = new Set(['hamburger-menu', 'menu-drawer', 'menu-panel']);
 /**
  * The overlay this node sits in, for the RENDER question "what must be opened
  * before I can photograph this".

package/dist/domains/site/readiness-fetch.js

@@ -89,6 +89,9 @@ export async function gatherReadiness(ctx, siteId, pageNodes, openPageId) {
     const blogCats = Array.isArray(rawBlogCats) ? rawBlogCats : null;
     const cats = categoryList?.categories ?? categoryList?.productCategories;
     const categories = Array.isArray(cats) ? (categoryList?.total ?? cats.length) : null;
+    const categoriesUnpictured = Array.isArray(cats)
+        ? cats.filter((c) => !String(c?.image ?? '').trim()).length
+        : null;
     const links = pageLinks?.links ?? pageLinks?.pageLinks;
     const categoryPageLinks = Array.isArray(links)
         ? links.filter((l) => l?.linkType === 'productCategory').length
@@ -159,6 +162,7 @@ export async function gatherReadiness(ctx, siteId, pageNodes, openPageId) {
             : null,
         overlayKinds: Array.isArray(overlayList?.overlays) ? overlayList.overlays.map((o) => o.kind ?? '') : null,
         categories,
+        categoriesUnpictured,
         categoryPageLinks,
         forms: formList?.forms ?? null,
         articles: Array.isArray(articleList?.articles)

package/dist/domains/site/readiness.js

@@ -612,6 +612,23 @@ export function readinessGaps(input) {
                 '/api/media/{siteId}/from-url ingests straight from a url in one hop.',
         });
     }
+    // A COLLECTION TILE WITH NO PICTURE IS A BROKEN-IMAGE ICON, not a grey card:
+    // render/nodes/collection-media writes `<img src="">` (the image element has a
+    // placeholder; this one does not). Measured on the sb_category_strip a store
+    // built here put on its home page — two broken icons above the category names.
+    // Asked only where a collection tile is actually on screen.
+    if ((input.categoriesUnpictured ?? 0) > 0 &&
+        [...input.pageNodes, ...(input.globalNodes ?? [])].some((n) => n.data?.type === 'collection-media')) {
+        const n = input.categoriesUnpictured;
+        gaps.push({
+            id: 'categoryImages',
+            draft: false,
+            problem: `${n} product categor${n === 1 ? 'y has' : 'ies have'} no image, and this page shows category ` +
+                'tiles — each renders a broken-image icon above its name.',
+            fix: 'Upload a picture (sb_media_upload), then PUT the category back with image: url ' +
+                '(sb_api_call put:/api/sites/{siteId}/product-categories/{id}, merge:true).',
+        });
+    }
     if (input.shippingMethods === 0) {
         gaps.push({
             id: 'shipping',

package/dist/domains/site/review.js

@@ -1,6 +1,8 @@
+import { isDeepStrictEqual } from 'node:util';
 import { childrenOf, childrenWithSatellites, isOverlay, isSharedSection, pageChildren, appBlockRoot, SPEC_GLOBAL_REF, SPEC_APP_BLOCK_REF } from '../../core/tree.js';
 import { STUCK_STATE, stickyBlockedBy, stuckHostOf, isPinnedNode } from './sticky.js';
-import { bandOf } from './traps.js';
+import { bandOf, isGlobal } from './traps.js';
+import { exampleCopy } from './examplecopy.js';
 import { HOVER_STATE, hoverHome } from './hover.js';
 import { ELEMENTS, BINDING_SOURCES, BOUND_SPECIALS, FIRST_CHILD_ONLY, SATELLITE_RULES, ELEMENT_SEEDS } from '../../catalog/elements.generated.js';
 import { fill } from './findings.js';
@@ -130,6 +132,33 @@ const LINK_SPECIALS = new Set(['boundHref', 'boundHrefLabel', 'boundProductURL']
 function drawsItsOwnContent(type) {
     return (BOUND_SPECIALS[type] ?? []).some((k) => !LINK_SPECIALS.has(k));
 }
+/** A literal #rgb / #rrggbb / rgb() colour as 0–255 channels, or null. */
+function rgbOf(v) {
+    const c = typeof v === 'string' ? v.trim().toLowerCase() : '';
+    if (c === 'white')
+        return [255, 255, 255];
+    if (c === 'black')
+        return [0, 0, 0];
+    const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/.exec(c);
+    if (hex) {
+        const h = hex[1].length === 3 ? hex[1].replace(/./g, (x) => x + x) : hex[1];
+        return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
+    }
+    const m = /^rgb\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)\s*\)$/.exec(c);
+    return m ? [m[1], m[2], m[3]].map(Number) : null;
+}
+/** WCAG contrast ratio of two sRGB colours. */
+function contrast(a, b) {
+    const lum = (rgb) => {
+        const [r, g, bl] = rgb.map((v) => {
+            const s = v / 255;
+            return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+        });
+        return 0.2126 * r + 0.7152 * g + 0.0722 * bl;
+    };
+    const [hi, lo] = [lum(a), lum(b)].sort((x, y) => y - x);
+    return (hi + 0.05) / (lo + 0.05);
+}
 /** Binding-source prefixes that name a RECORD (not `site.*`, which every page has). */
 // cartLine: only a cart-order's line row supplies it (render/nodes/cart-order,
 // scope.PlaceholderCartLine) — see ROW_SUPPLIER. searchRow is left out: no
@@ -248,6 +277,27 @@ opts = {}) {
         });
         return out;
     }
+    // ONLY THE SHARED HEADER AND FOOTER is a blank page too. Measured: an "account"
+    // page created by sb_page_create (no seed for that type) wore the site chrome
+    // and nothing else, reviewed clean, and so did the readiness gap it was made
+    // to close — a shopper landing on /account met a header, a footer and nothing.
+    // Composed (globalId, what a read carries) or stored (globalRef) alike.
+    // HEADER AND FOOTER only: a `custom` shared section is body content.
+    const isChrome = (id) => {
+        const sp = d.nodes[id]?.specials ?? {};
+        if (isGlobal(d, id))
+            return bandOf(d, id) !== 'middle';
+        return sp[SPEC_GLOBAL_REF] !== undefined && (sp.globalKind === 'header' || sp.globalKind === 'footer');
+    };
+    if (pageChildren(d).every(isChrome)) {
+        out.push({
+            code: 'empty_page',
+            nodeId: d.root_node_id,
+            type: 'root',
+            problem: 'Only the shared header and footer — the page between them is blank.',
+            fix: fill('empty_page', {}),
+        });
+    }
     // Document order, depth-first from ROOT: the order a reader meets them.
     const seen = new Set();
     const walkOrder = [];
@@ -383,6 +433,54 @@ opts = {}) {
             });
             continue;
         }
+        // TYPE THE SAME COLOUR AS WHAT IT SITS ON. Measured: a pattern dressed in
+        // tokens read off an inverted band published a white "Mua ngay" on its own
+        // white fill — present in the HTML, invisible on the page, clean in review.
+        // LITERAL COLOURS ONLY, on both sides, and the ground is the element's own
+        // fill or the nearest ancestor that sets one: a theme var or an unset page
+        // ground is not known here, and a dark theme would make a guessed "white"
+        // ground cry wolf on every light heading.
+        if ((type === 'text' || type === 'heading' || type === 'button') && !inOverlay.has(id)) {
+            const fg = rgbOf(n.style?.color);
+            let ground = null;
+            for (let x = id; x && d.nodes[x] && !ground; x = d.nodes[x].data.parent) {
+                const bg = d.nodes[x].style?.backgroundColor;
+                if (bg === undefined || bg === 'transparent' || bg === '')
+                    continue;
+                ground = rgbOf(bg);
+                if (!ground)
+                    break; // a var() or a gradient: unknown, say nothing
+            }
+            if (fg && ground && contrast(fg, ground) < 1.5) {
+                out.push({
+                    code: 'invisible_text',
+                    nodeId: id,
+                    type,
+                    problem: `Its colour is the colour it sits on (contrast ${contrast(fg, ground).toFixed(2)}:1) — the words are there and nobody can read them.`,
+                    fix: fill('invisible_text', { id }),
+                });
+            }
+        }
+        // THE DEMO OPTIONS. product-variants seeds config.attributes Color
+        // Red/Green/Blue, Size S/M/L, and that authored config is the documented
+        // FALLBACK for a product with no option axes of its own (schema binding.ts:
+        // "the picker keeps its authored config"). So every simple product on a
+        // published page offered three colours and three sizes that do not exist —
+        // measured on a store built here, and reviewed clean.
+        if (type === 'product-variants') {
+            const authored = n.config?.attributes;
+            const seeded = ELEMENTS[type]?.defaults?.config?.attributes;
+            if (Array.isArray(seeded) && seeded.length && isDeepStrictEqual(authored, seeded)) {
+                out.push({
+                    code: 'demo_variant_options',
+                    nodeId: id,
+                    type,
+                    problem: 'Still the picker\'s demo options (Color Red/Green/Blue, Size S/M/L). They render for ' +
+                        'every product that has no options of its own — a shopper is offered choices that do not exist.',
+                    fix: fill('demo_variant_options', { id }),
+                });
+            }
+        }
         // A NAVIGATION CONTROL WITH NOWHERE TO GO, and it is the sharpest silent
         // failure on this list because the page is CORRECT in every way a check can
         // otherwise see. The tree holds the event the author asked for; the pixels
@@ -669,11 +767,18 @@ opts = {}) {
         // is "add something inside it", which on the next save is decomposed away
         // again. Measured on a page built with `sb_add`: the header and footer refs
         // both flagged, and both correct.
+        // OR IT DRAWS ITS OWN CONTROL. `search-input` is a container only for the
+        // dropdown an author MAY compose under it; with no children it still renders
+        // its `<input>` (render/nodes/search-input/html.go). The platform's own
+        // search seed ships it childless, so every seeded search page was flagged.
+        // Not `select`: its face lives in its trigger/panel children.
+        const drawsOwnControl = type === 'search-input';
         const isReference = (n.specials ?? {})[SPEC_GLOBAL_REF] !== undefined ||
             (n.specials ?? {})[SPEC_APP_BLOCK_REF] !== undefined;
         if (meta.isContainer &&
             childrenOf(d, id).length === 0 &&
             !isReference &&
+            !drawsOwnControl &&
             !(bindings.length > 0 && drawsItsOwnContent(type))) {
             out.push({
                 code: 'empty_container',
@@ -762,6 +867,19 @@ opts = {}) {
                     fix: fill('default_seed_copy', { id, key }),
                 });
             }
+            // A BUILT-IN LAYOUT'S EXAMPLE COPY — see examplecopy.ts.
+            else if (typeof value === 'string' && exampleCopy().has(value)) {
+                out.push({
+                    code: 'example_copy',
+                    nodeId: id,
+                    type,
+                    problem: `Still the "${exampleCopy().get(value)}" layout's example copy (${JSON.stringify(value)}). ` +
+                        'A shopper reads it as this shop speaking — and a number, a promise or a ' +
+                        'testimonial in it is a claim nobody made.',
+                    key,
+                    fix: fill('example_copy', { id, key }),
+                });
+            }
         }
         // A FORM NOBODY LINKED publishes as an empty box, and the platform stays
         // deliberately quiet about it: form.go:221 skips an empty formId with the

package/dist/tools/api.js

@@ -455,7 +455,7 @@ export function resolveOperation(args) {
             'method+path for a route the catalog does not carry.');
     }
     if (args.id) {
-        const op = API_OPERATIONS.find((o) => o.id === args.id);
+        const op = findOperation(args.id);
         if (!op)
             throw new Error(`sbuilder: unknown operation "${args.id}" — use sb_api_find first`);
         return op;

package/dist/tools/page.js

@@ -24,6 +24,7 @@ import { siteToken } from './credentialpick.js';
 import { validateForSave } from '../domains/site/validate.js';
 import { formDocChecks, sayChecks, specCheck, writeCheck } from '../domains/site/writecheck.js';
 import { reviewDesign, REVIEW_NOTICE } from '../domains/site/review.js';
+import { exampleCopy } from '../domains/site/examplecopy.js';
 import { compactFindings } from '../domains/site/findings.js';
 import { readinessGaps, READINESS_NOTICE, siteLanguage } from '../domains/site/readiness.js';
 import { gatherReadiness } from '../domains/site/readiness-fetch.js';
@@ -1427,7 +1428,16 @@ export function registerPageTools(server, ctx) {
     }, async ({ parent_id, spec, index, dry_run, force }) => {
         const d = session.current();
         const guard = { force, forced: [] };
-        const { patches, ids } = addSubtree(d, parent_id, spec, index, guard);
+        // ROOT WITH NO INDEX MEANS "ANOTHER SECTION OF THE PAGE": the end of the
+        // middle band, as sb_template_use and sb_duplicate already place one.
+        // Appended last it landed after a shared footer, and the band-order check
+        // refused the save — on exactly the call empty_page's fix names.
+        // Only when a footer is there to land behind: a FORM document's root has
+        // none, and addSubtree's own default (above the submit button) is right.
+        const rootKids = d.doc.nodes[d.doc.root_node_id]?.data.nodes.length ?? 0;
+        const mid = parent_id === d.doc.root_node_id ? middleEnd(d.doc) : rootKids;
+        const at = index ?? (mid < rootKids ? mid : undefined);
+        const { patches, ids } = addSubtree(d, parent_id, spec, at, guard);
         const forced = guard.forced.length ? { forced: guard.forced } : {};
         // ELEMENTS THAT RENDER CONVINCINGLY WHILE WIRED TO NOTHING. The add
         // succeeds completely, the tree is correct and the page photographs
@@ -2045,9 +2055,22 @@ export function registerPageTools(server, ctx) {
                 });
             }
             await session.applyAndSave(patches);
+            // Say it at the moment it is placed: the example copy publishes as if the
+            // shop wrote it, and sb_review is the only other place it surfaces.
+            const examples = ids.filter((id) => {
+                const sp = doc.doc.nodes[id]?.specials ?? {};
+                return ['text', 'label', 'alt'].some((k) => typeof sp[k] === 'string' && exampleCopy().has(sp[k]));
+            }).length;
             return text({
                 added: pattern.name,
                 section: ids[0],
+                ...(examples
+                    ? {
+                        copy: `${examples} element(s) still carry the layout's example copy — write this shop's own ` +
+                            'words over them (sb_review lists each as example_copy); remove any number, promise ' +
+                            'or quote you cannot vouch for.',
+                    }
+                    : {}),
                 nodes: ids.length,
                 into: page_id,
                 rev: doc.rev,
@@ -2429,10 +2452,21 @@ export function registerPageTools(server, ctx) {
         // entity URL once published — say what to add, whatever the reason
         // (no platform seed, seed:false, a refused seed write).
         const blankNote = !seeded || 'failed' in seeded ? emptyEntityTemplateNote(type) : null;
+        // A LAYOUT is the editor's skeleton, and it ships its elements' own
+        // placeholders ("Heading", "Enter your text here", an image with no src).
+        // Measured: an "about" page created here reviewed with four findings before
+        // anything else was done, and the create answer had said nothing about it.
+        const skeletonFindings = seeded && 'layout' in seeded && layout
+            ? reviewDesign(PageDoc.from(layoutDocument(layout)), { pageType: type ?? 'page' }).length
+            : 0;
+        const skeletonNote = skeletonFindings
+            ? `This is the "${String(seeded?.layout)}" skeleton and it already has ${skeletonFindings} ` +
+                'finding(s) — placeholder copy, empty slots. Open it and fill them; sb_review lists each.'
+            : null;
         return text({
             ...res,
             ...(seeded ? { seeded } : {}),
-            ...(blankNote ? { next: blankNote } : {}),
+            ...(blankNote ? { next: blankNote } : skeletonNote ? { next: skeletonNote } : {}),
             ...(wearing ? { chrome: wearing } : {}),
             ...(renamed
                 ? {

package/package.json

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