sbuilder-mcp 0.86.0 → 0.88.0

package/CHANGELOG.md

@@ -6,6 +6,35 @@ 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.88.0] - 2026-10-12
+
+### Added
+- `sb_review` reports `default_seed_copy` for pages built earlier that still carry the English seed copy, such as "Add To Cart", on a Vietnamese site, with the Vietnamese wording to use instead.
+
+### Changed
+- `sb_page_create` writes the store page seeds in Vietnamese for a Vietnamese site, taking the locale from the site's settings when none is passed.
+- `sb_page_create` uses English thank-you copy on the completed-order page of an `en-US` site.
+- `sb_review` words its `categoryImages` note to say that a collection tile without an image now shows a placeholder instead of a broken image.
+
+## [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

package/CHANGELOG.vi.md

@@ -6,6 +6,35 @@ 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.88.0] - 2026-10-12
+
+### Added
+- `sb_review` báo `default_seed_copy` cho trang dựng trước đó còn mang chữ mẫu tiếng Anh, như "Add To Cart", trên site tiếng Việt, kèm bản tiếng Việt nên dùng.
+
+### Changed
+- `sb_page_create` viết seed trang cửa hàng bằng tiếng Việt cho site tiếng Việt, lấy locale từ cài đặt của site khi không truyền.
+- `sb_page_create` dùng câu cảm ơn tiếng Anh cho trang hoàn tất đơn hàng của site `en-US`.
+- `sb_review` sửa câu báo `categoryImages`: ô danh mục thiếu ảnh giờ hiện placeholder thay vì ảnh vỡ.
+
+## [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

package/dist/catalog/deadkeys.generated.js

@@ -1,6 +1,6 @@
 export const DEAD_KEY_SOURCE = {
-    "files": 5688,
-    "identifiers": 104011,
+    "files": 5692,
+    "identifiers": 104086,
     "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

@@ -4,7 +4,7 @@ export const SHAPE_SOURCE = {
     "fromHandlers": 302,
     "fromSwaggerOnly": 10,
     "withReadOnly": 30,
-    "structsRead": 3224
+    "structsRead": 3226
 };
 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": "c296c1a134378574c7d8643ce020485c3c53535b",
-    "committedAt": "2026-10-12T01:19:39+07:00",
+    "commit": "74ca59dd2340133e4ecf7f2faaf0947874ec3554",
+    "committedAt": "2026-10-12T10:37:24+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,24 @@ export function readinessGaps(input) {
                 '/api/media/{siteId}/from-url ingests straight from a url in one hop.',
         });
     }
+    // A COLLECTION TILE WITH NO PICTURE. Measured on the sb_category_strip a store
+    // built here put on its home page: render/nodes/collection-media wrote
+    // `<img src="">`, two broken icons above the category names. web_builder PR
+    // #118 (74ca59dd2) gives it the image element's grey placeholder instead —
+    // better, still not the category. Asked only where a tile is 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 draws the platform's grey placeholder (a broken-image icon on a platform " +
+                'older than web_builder 74ca59dd2) where the picture goes.',
+            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,9 @@
+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 { SEED_COPY_VI, langOf } from './seedcopy.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 +133,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 +278,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 +434,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 +768,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 +868,36 @@ opts = {}) {
                     fix: fill('default_seed_copy', { id, key }),
                 });
             }
+            // THE STORE SEEDS' ENGLISH COPY ON A VIETNAMESE SITE ("Add To Cart") —
+            // fine on an English site, so asked only when the site's language is
+            // known. sb_page_create now seeds it in Vietnamese; this is for pages
+            // made before that, or with locale:"en" on a Vietnamese site.
+            else if (typeof value === 'string' &&
+                SEED_COPY_VI[value] &&
+                langOf(opts.siteLocale) === 'vi') {
+                out.push({
+                    code: 'default_seed_copy',
+                    nodeId: id,
+                    type,
+                    problem: `Still the platform's English seed copy (${JSON.stringify(value)}) on a Vietnamese site — ` +
+                        `"${SEED_COPY_VI[value]}" is what this storefront should say.`,
+                    key,
+                    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/domains/site/seedcopy.js

@@ -0,0 +1,28 @@
+/**
+ * THE STORE SEEDS' ENGLISH COPY, IN VIETNAMESE — applied when the page is made
+ * for a Vietnamese site.
+ *
+ * The platform seeds in English on purpose (editor/src/element/emptyState.ts:
+ * "a seed is a seed", decided 2026-09-17) and a table per language was offered
+ * there and declined. Here the agent IS the author, and it knows the site's
+ * language: measured on a store built end to end, the product page published
+ * "Add To Cart" / "Buy It Now" to a Vietnamese storefront and every page
+ * reviewed clean. sb_page_create seeds through this; sb_review (which reads the
+ * site's locale) reports a page still carrying the English. Exact strings only; a seed string
+ * this table does not carry is left as it was — and test/store-page-seeds
+ * fails when codegen brings one in, so the table cannot fall behind silently.
+ */
+export const SEED_COPY_VI = {
+    'Add To Cart': 'Thêm vào giỏ',
+    'Buy It Now': 'Mua ngay',
+    'This item is unavailable': 'Sản phẩm tạm hết',
+    'It may have been removed. Have a look at the rest of the shop.': 'Sản phẩm có thể đã ngừng bán. Mời bạn xem các sản phẩm khác.',
+    'No products yet': 'Chưa có sản phẩm',
+    'New arrivals will show up here. Check back soon.': 'Sản phẩm mới sẽ sớm có ở đây — mời bạn quay lại sau.',
+    'No posts yet': 'Chưa có bài viết',
+    'New stories will show up here. Check back soon.': 'Bài viết mới sẽ sớm có ở đây.',
+};
+/** The language part of a locale tag — "vi-VN", "vi_VN" and "VI" are all "vi". */
+export function langOf(locale) {
+    return String(locale ?? '').toLowerCase().split(/[-_]/)[0];
+}

package/dist/domains/site/storepage.js

@@ -1,3 +1,4 @@
+import { SEED_COPY_VI, langOf } from './seedcopy.js';
 import { COMPLETION_HEADLINE, COMPLETION_HEADLINE_SENTINEL, PAGE_LAYOUT_SEEDS, PAGE_TYPES, STORE_PAGE_SEEDS } from '../../catalog/storepages.generated.js';
 import { BINDING_SOURCES } from '../../catalog/elements.generated.js';
 import { withFreshIds } from './ids.js';
@@ -40,22 +41,44 @@ export function seededTypes() {
  * An explicit `headline` wins over both — a merchant's own wording is not the
  * client's to overrule.
  */
+/** Rewrite every exact seed string the table carries, in place. */
+function localizeSeed(doc, table) {
+    for (const n of Object.values(doc.nodes)) {
+        const sp = n.specials;
+        if (!sp)
+            continue;
+        for (const k of ['text', 'label']) {
+            const v = sp[k];
+            if (typeof v === 'string' && table[v])
+                sp[k] = table[v];
+        }
+    }
+}
+export { SEED_COPY_VI } from './seedcopy.js';
 export function seedDocument(type, opts = {}) {
     const seed = STORE_PAGE_SEEDS[type];
     if (!seed)
         return null;
     const raw = JSON.stringify(seed);
+    const vi = langOf(opts.locale ?? 'vi') === 'vi';
+    const out = (doc) => {
+        if (vi)
+            localizeSeed(doc, SEED_COPY_VI);
+        return withFreshIds(doc);
+    };
     // Fresh ids per create, so two pages from one seed share nothing but ROOT.
     if (!raw.includes(COMPLETION_HEADLINE_SENTINEL)) {
-        return withFreshIds(JSON.parse(raw));
+        return out(JSON.parse(raw));
     }
-    const lang = opts.locale && opts.locale in COMPLETION_HEADLINE ? opts.locale : 'vi';
+    // Normalized: a site whose locale is "en-US" reads its own language here too.
+    const tag = langOf(opts.locale);
+    const lang = tag && tag in COMPLETION_HEADLINE ? tag : 'vi';
     const headline = opts.headline || COMPLETION_HEADLINE[lang];
     // JSON.stringify already escaped the seed; the substitute has to be escaped
     // the same way or an apostrophe in a merchant's own headline breaks the
     // document. Slicing the quotes off a stringified string is that escaping.
     const escaped = JSON.stringify(headline).slice(1, -1);
-    return withFreshIds(JSON.parse(raw.split(COMPLETION_HEADLINE_SENTINEL).join(escaped)));
+    return out(JSON.parse(raw.split(COMPLETION_HEADLINE_SENTINEL).join(escaped)));
 }
 /**
  * What to put on an ENTITY TEMPLATE that opens empty, or null.

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';
@@ -46,8 +47,8 @@ import { projectList, PAGE_FIELDS, TEMPLATE_FIELDS } from './project.js';
  * copies of a directive is how one of them quietly loses it. The fix for each
  * KIND is sent once under `fixes`, and the directive once per process.
  */
-export function reviewField(ctx, doc, formTypes, pageType, formDocType, formRedirects) {
-    const all = reviewDesign(doc, { formTypes, pageType, formDocType, formRedirects });
+export function reviewField(ctx, doc, formTypes, pageType, formDocType, formRedirects, siteLocale) {
+    const all = reviewDesign(doc, { formTypes, pageType, formDocType, formRedirects, siteLocale });
     if (all.length === 0)
         return {};
     // MAINTENANCE IS ADVICE, kept out of `findings`: it works for a visitor, so
@@ -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
@@ -1797,6 +1807,7 @@ export function registerPageTools(server, ctx) {
         // The page's TYPE says which record it supplies — `no_data_context` stays
         // silent without it rather than guessing.
         let pageType;
+        let siteLocale;
         try {
             const { siteId, pageId } = session.location();
             const input = await gatherReadiness(ctx, siteId, Object.values(doc.doc.nodes), pageId);
@@ -1807,6 +1818,7 @@ export function registerPageTools(server, ctx) {
                 return f.id && a?.action === 'redirect' && (a.url || a.pageId) ? [f.id] : [];
             }));
             pageType = input.pages?.find((p) => p.id === pageId)?.type;
+            siteLocale = input.siteLocale;
             const gaps = readinessGaps(input);
             const lang = siteLanguage(input.siteLocale, input.pageNodes);
             const said = lang ? ctx.notices.once(`site-language:${siteId}`, lang) : undefined;
@@ -1820,7 +1832,7 @@ export function registerPageTools(server, ctx) {
         catch {
             // Readiness is additional information, never the reason a review fails.
         }
-        const field = reviewField(ctx, doc, formTypes, pageType, session.formType(), formRedirects);
+        const field = reviewField(ctx, doc, formTypes, pageType, session.formType(), formRedirects, siteLocale);
         // Clean = no finding a visitor meets; `advice` (maintenance) rides beside the verdict.
         const clean = !field.findings;
         return text({
@@ -2045,9 +2057,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,
@@ -2214,7 +2239,7 @@ export function registerPageTools(server, ctx) {
             settings: z.record(z.unknown()).optional(),
             seed: z.boolean().optional().describe('Default true; false creates a blank page.'),
             chrome: z.boolean().optional().describe("Carry the site's header and footer, default true"),
-            locale: z.string().optional().describe("vi (default) or en — the complete page's wording."),
+            locale: z.string().optional().describe("vi or en — a store seed's wording; defaults to the site's language, else vi."),
             headline: z.string().optional().describe("The complete page's thank-you line."),
             dry_run: z.boolean().optional(),
         },
@@ -2397,7 +2422,25 @@ export function registerPageTools(server, ctx) {
         let seeded = null;
         const newId = res.page?.id;
         if ((willSeed || layout) && typeof newId === 'string' && newId) {
-            const document = layout ? layoutDocument(layout) : seedDocument(type ?? '', { locale, headline });
+            // The SITE's language when the caller named none — the seed's English
+            // copy is rewritten for a Vietnamese site (SEED_COPY_VI). Unreadable
+            // settings fall back to the old default rather than block the create.
+            const lang = locale ??
+                (layout
+                    ? undefined
+                    : await request({
+                        base: ctx.base,
+                        method: 'GET',
+                        path: `/api/sites/${encodeURIComponent(site_id)}/settings`,
+                        token: siteToken(ctx),
+                        fetchImpl: ctx.fetchImpl,
+                    })
+                        .then((r) => {
+                        const l = r?.settings?.locale;
+                        return typeof l === 'string' && l ? l : undefined;
+                    })
+                        .catch(() => undefined));
+            const document = layout ? layoutDocument(layout) : seedDocument(type ?? '', { locale: lang, headline });
             if (document) {
                 try {
                     await request({
@@ -2429,10 +2472,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.86.0",
+  "version": "0.88.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",