sbuilder-mcp 0.29.0 → 0.30.1

package/CHANGELOG.md

@@ -6,6 +6,28 @@ 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.30.1] - 2026-09-11
+
+### Changed
+- sb_import and sb_import_site's default `max_images` and `max_nodes` rise from 24/300 to 60/900, so a real shop homepage's full catalogue is no longer cut off mid-band.
+- A flex or grid container that wraps is now capped at 60 columns per row instead of 12, so a wide product shelf is captured as its own row instead of being coerced into a vertical stack.
+
+### Fixed
+- sb_import and sb_import_site no longer read images from `src` alone: a lazy-loaded `data-src`/`data-original`/`data-lazy-src`/`srcset` (widest candidate) is now read as the real photo, so a lazy-loaded product gallery is no longer imported as a handful of pictures with the rest reported as missing.
+- Content hidden inside a tab panel, carousel slide or filtered grid (`display:none` beside a visible sibling of the same kind) is now revealed and captured, so a homepage that lays its catalogue out in tabs no longer loses every tab but the one shown at load.
+- `<button>` elements are no longer skipped as form controls: a button with words in it is now captured as a call-to-action or link the same way an `<a>` is, so "Add to cart"-style buttons are no longer dropped from the import.
+- The section-candidate fallback now fires whenever the chosen sections cover under half of the page's non-chrome text, not only when they capture nothing at all, so a page whose only `<section>` elements are a breadcrumb no longer imports as that breadcrumb alone.
+
+## [0.30.0] - 2026-09-10
+
+### Added
+- A new tool, sb_theme, reads the site's colour tokens and text styles and can now write them: `colors` and `text_styles` patch the saved theme document, keeping every field you do not name, and an unknown token id or style slug is refused with the real ones listed. A site that has never saved a theme reads back the starter theme rather than an empty document.
+- sb_traits_for now describes `config.animation` on every element that offers it (73 of 111), naming the four ways a write silently renders nothing: it must be an object rather than a bare string, `active: true` is required, the `type` value is spelled with underscores, and the write is base-only.
+- sb_set now warns when a `config.animation` write will not animate: a value that is not an object, a missing `active: true`, an unrecognised `type`, or an unrecognised `easing` (which falls back to a curve you did not choose) are each named individually.
+
+### Fixed
+- sb_set now routes a `config.animation` write to the base breakpoint instead of a per-breakpoint slot the renderer never reads, closing the fourth silent way to lose the animation.
+
 ## [0.29.0] - 2026-09-10
 
 ### Added

package/CHANGELOG.vi.md

@@ -6,6 +6,28 @@ 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.30.1] - 2026-09-11
+
+### Changed
+- Giá trị mặc định `max_images` và `max_nodes` của sb_import và sb_import_site tăng từ 24/300 lên 60/900, nên toàn bộ catalogue trên trang chủ một shop thật không còn bị cắt cụt giữa chừng một band.
+- Một container flex hoặc grid có wrap giờ được giới hạn 60 cột mỗi hàng thay vì 12, nên một kệ sản phẩm rộng được chụp lại đúng thành một hàng thay vì bị ép thành một cột dọc.
+
+### Fixed
+- sb_import và sb_import_site không còn chỉ đọc ảnh từ `src`: một ảnh lazy-load qua `data-src`/`data-original`/`data-lazy-src`/`srcset` (chọn ứng viên rộng nhất) giờ được đọc như ảnh thật, nên một thư viện ảnh sản phẩm lazy-load không còn bị nhập vào với vài tấm còn lại bị báo là thiếu.
+- Nội dung ẩn trong một tab panel, slide carousel hay lưới lọc (`display:none` cạnh một anh em cùng loại đang hiển thị) giờ được hiện ra và chụp lại, nên một trang chủ trình bày catalogue theo dạng tab không còn mất hết các tab trừ tab đang mở lúc tải.
+- Phần tử `<button>` không còn bị bỏ qua như một control của form: một button có chữ bên trong giờ được chụp lại như một nút kêu gọi hành động hoặc liên kết, giống cách một `<a>` được xử lý, nên các nút kiểu "Thêm vào giỏ" không còn bị rớt khỏi bản nhập.
+- Cơ chế dự phòng chọn section giờ kích hoạt bất cứ khi nào các section được chọn chỉ phủ dưới một nửa nội dung chữ không phải chrome của trang, chứ không chỉ khi chúng không chụp được gì cả, nên một trang mà các phần tử `<section>` duy nhất là một breadcrumb sẽ không còn bị nhập vào chỉ như breadcrumb đó.
+
+## [0.30.0] - 2026-09-10
+
+### Added
+- Một tool mới, sb_theme, đọc bảng màu và text style của site và giờ có thể ghi chúng: `colors` và `text_styles` patch vào theme document đã lưu, giữ nguyên mọi trường không được nêu tên, còn một token id hay style slug không tồn tại sẽ bị từ chối kèm danh sách các id thật. Một site chưa từng lưu theme sẽ đọc lại theme mặc định (starter) thay vì một document rỗng.
+- sb_traits_for giờ mô tả `config.animation` trên mọi element có cung cấp nó (73 trong 111 element), nêu rõ bốn cách khiến việc ghi âm thầm không tạo ra hiệu ứng nào: nó phải là một object thay vì một chuỗi đơn thuần, `active: true` là bắt buộc, giá trị `type` được viết bằng dấu gạch dưới, và việc ghi chỉ áp dụng ở base breakpoint.
+- sb_set giờ cảnh báo khi một lệnh ghi `config.animation` sẽ không tạo hiệu ứng: giá trị không phải object, thiếu `active: true`, `type` không nhận diện được, hoặc `easing` không nhận diện được (sẽ rơi về một đường cong bạn không hề chọn) — mỗi trường hợp được nêu tên riêng.
+
+### Fixed
+- sb_set giờ định tuyến lệnh ghi `config.animation` vào breakpoint base thay vì một vị trí theo từng breakpoint mà renderer không bao giờ đọc tới, khép lại cách thứ tư khiến hiệu ứng bị mất một cách âm thầm.
+
 ## [0.29.0] - 2026-09-10
 
 ### Added

package/README.md

@@ -108,6 +108,7 @@ in this client: one would put the very key the platform exists to hold back into
 | `sb_bind` | Bind a node's content to real store data, or make a button add to the cart |
 | `sb_import` | Read a page from any public URL and add its structure and content to the open page as real elements, styled with THIS page's own tokens — a translation, not a clone |
 | `sb_import_site` | Read a WHOLE site from one URL — its sitemap, or the links on that page — and give each page found its own draft page here, built from this site's tokens |
+| `sb_theme` | Read or patch the site's palette and type scale — the layer every style preset resolves from, so one token repaints every page |
 | `sb_store` | Run a store flow that must happen in a fixed order — the four writes that make a working checkout, or any of the platform's 17 form templates (login, register, forgot, contact, subscribe …) with its own field document |
 | `sb_undo` | Put back what a PUT replaced — the platform has no page history or restore, so this is the only way back |
 

package/README.vi.md

@@ -105,6 +105,7 @@ nhét ngược lại vào mọi bản cài.
 | `sb_bind` | Gắn nội dung một node vào dữ liệu cửa hàng thật, hoặc biến một nút thành nút thêm vào giỏ |
 | `sb_import` | Đọc một trang từ URL công khai bất kỳ và thêm cấu trúc + nội dung của nó vào trang đang mở dưới dạng element thật, mang token của CHÍNH trang này — là dịch lại, không phải sao chép |
 | `sb_import_site` | Đọc CẢ website từ một URL — sitemap của nó, hoặc các link trên trang đó — và tạo cho mỗi trang tìm được một trang nháp riêng ở đây, dựng bằng token của site này |
+| `sb_theme` | Đọc hoặc vá bảng màu và thang chữ của site — tầng mà mọi style preset phân giải từ đó, nên một token thay áo cho mọi trang |
 | `sb_store` | Chạy một luồng cửa hàng bắt buộc đúng thứ tự — bốn lệnh ghi tạo nên trang thanh toán, hoặc gieo bất kỳ template nào trong 17 form của nền tảng (login, register, forgot, contact, subscribe …) kèm field document của nó |
 | `sb_undo` | Trả lại thứ mà một lệnh PUT đã ghi đè — nền tảng không có lịch sử trang hay restore, nên đây là đường về duy nhất |
 

package/dist/catalog/api.generated.js

@@ -1,7 +1,7 @@
 export const SWAGGER_SOURCE = {
     "operations": 501,
-    "definitions": 104,
-    "bodyCarrying": 178,
+    "definitions": 105,
+    "bodyCarrying": 179,
     "bodyUndescribed": 64,
     "generatedFrom": "server/docs/swagger.json"
 };
@@ -12958,18 +12958,25 @@ export const API_OPERATIONS = [
         "tags": [
             "templates"
         ],
-        "summary": "The site templates a new store can be created from",
+        "summary": "Create a site from a template",
         "params": [
             {
                 "name": "siteId",
                 "in": "path",
                 "required": true,
                 "type": "string",
-                "description": "Site to apply the template to (POST)"
+                "description": "Template site to start from"
+            },
+            {
+                "name": "body",
+                "in": "body",
+                "required": true,
+                "type": "object",
+                "description": "The new site's name"
             }
         ],
-        "bodyDescribed": false,
-        "bodyRef": null,
+        "bodyDescribed": true,
+        "bodyRef": "internal_templates_rest.useBody",
         "credential": "siteScoped"
     },
     {
@@ -17923,5 +17930,14 @@ export const API_DEFINITIONS = {
                 "type": "integer"
             }
         }
+    },
+    "internal_templates_rest.useBody": {
+        "type": "object",
+        "properties": {
+            "name": {
+                "description": "Name is the new site's name. Required rather than defaulted to the\ntemplate's own name: a default would quietly produce two sites called\n\"Fashion starter\" for a user who pressed the button twice.",
+                "type": "string"
+            }
+        }
     }
 };

package/dist/catalog/element-search.js

@@ -1,5 +1,5 @@
 import { ELEMENTS, TRAIT_WRITES } from './elements.generated.js';
-import { vocabulariesForWrites } from '../domains/site/vocabulary.js';
+import { animationVocabulary, vocabulariesForWrites } from '../domains/site/vocabulary.js';
 import { neverTranslatedOn, translatableSpecials } from '../domains/site/translate.js';
 /** Eight to choose from; the hints for the chosen one come with sb_traits_for. */
 export const DEFAULT_CATALOG_LIMIT = 8;
@@ -125,6 +125,12 @@ export function traitsFor(type, control) {
             const vocab = vocabulariesForWrites([...keys]);
             return Object.keys(vocab).length ? { config_values: vocab } : {};
         })(),
+        // THE ENTRANCE ANIMATION, for the 73 element types that offer it. It does
+        // not ride in `config_values` because it is not a word — it is an OBJECT
+        // with a required gate, and the three ways to get it wrong all render
+        // NOTHING rather than something else. An element that does not offer the
+        // control says nothing, so this is silent on the other 38.
+        ...(el.controls.includes('animation') ? { animation: animationVocabulary() } : {}),
         isContainer: el.isContainer,
         isRootOnly: el.isRootOnly,
         childAllows: el.childAllows,

package/dist/catalog/elements.generated.js

@@ -36188,6 +36188,7 @@ export const BASE_ONLY_CONFIG = [
     "collectionId",
     "collectionType",
     "quantity",
+    "animation",
     "rowLimit"
 ];
 /**
@@ -36198,3 +36199,36 @@ export const BASE_ONLY_CONFIG = [
 export const BASE_ONLY_EXCEPTIONS = [
     "quantity-button:iconSize"
 ];
+/**
+ * The ENTRANCE ANIMATION's vocabulary — config.animation, offered by 73 of the
+ * 111 element types and describable by nothing until now.
+ *
+ * Three ways to miss, all silent (AnimationTypeOf answers "" and no keyframes,
+ * no rule and no error are emitted, through save, publish and render):
+ *   - it is an OBJECT, not a string: {active, type, easing, delay, duration}
+ *   - active:true is REQUIRED; a stored type is deliberately NOT consent,
+ *     because the panel keeps the type when the switch goes off
+ *   - type is a keyframe key spelled with UNDERSCORES: fade_in, never fade-in
+ *
+ * easing is the mild one: an unrecognised value falls back to "ease".
+ *
+ * It is also BASE-ONLY (see BASE_ONLY_CONFIG) — render/css.go emits it into the
+ * base lane because the config object is read with no responsive merge.
+ */
+export const ANIMATION = {
+    "types": [
+        "fade_in",
+        "slide_down",
+        "slide_up",
+        "zoom_in"
+    ],
+    "easings": [
+        "ease",
+        "ease-in",
+        "ease-out",
+        "linear"
+    ],
+    "easingFallback": "ease",
+    "durationDefault": 0.5,
+    "readBy": "AnimationTypeOf + CompileEntranceAnimationCSS"
+};

package/dist/domains/site/vocabulary.js

@@ -1,4 +1,4 @@
-import { CONFIG_VALUES } from '../../catalog/elements.generated.js';
+import { ANIMATION, CONFIG_VALUES } from '../../catalog/elements.generated.js';
 /** The vocabulary for a config key, or null when the key has no fixed one. */
 export function vocabularyFor(key) {
     return CONFIG_VALUES[key] ?? null;
@@ -55,3 +55,90 @@ export function unknownValueNote(key, value) {
             : '') +
         '.');
 }
+/**
+ * THE ENTRANCE ANIMATION, WHICH 73 OF 111 ELEMENTS OFFER AND NOTHING DESCRIBED.
+ *
+ * Same family as the vocabularies above and worse in one way: there are THREE
+ * ways to miss and all of them are silent, because `AnimationTypeOf` answers ""
+ * and `render/css.go` then emits no keyframes, no rule and no error — through
+ * save, publish and render.
+ *
+ *   - IT IS AN OBJECT, not the string the control's name invites.
+ *     `readAnimConfig` asserts `map[string]interface{}`, so a bare
+ *     `"fade_in"` is the zero value and the node never animates.
+ *   - `active: true` IS REQUIRED, and a stored `type` is deliberately NOT
+ *     consent. The platform's own comment gives the reason: the panel keeps
+ *     `type` when the switch goes off, so switching back restores the choice —
+ *     "treating a stored type as consent would animate a node the author had
+ *     explicitly turned off".
+ *   - THE TYPE IS UNDERSCORED. `AnimKeyframes`'s comment flags it outright:
+ *     "keyed by the STORED value (`fade_in`, not `fade-in`)". `fade-in` is the
+ *     spelling every other web tool uses and the one an agent reaches for.
+ *
+ * `easing` is the mild case and is reported differently: an unrecognised value
+ * falls back to `ease`, so the animation still runs — it is a wrong answer, not
+ * a missing one.
+ *
+ * And it is BASE-ONLY, which is a fourth way to lose it — but that one is
+ * ROUTED rather than warned about, by `baseonly.ts`, because the platform's
+ * ledger names the key and `sb_set` can simply write it to the right layer.
+ */
+export const ANIMATION_VOCAB = ANIMATION;
+/**
+ * Everything a caller needs to write config.animation correctly, in ONE LINE.
+ *
+ * It rides on 73 of the 111 elements, and `sb_traits_for` is the result an agent
+ * reads before every styling decision — so the first version of this, a
+ * six-field object, was 400 bytes of dilution on two thirds of the catalog and
+ * pushed the search-result budget over its ceiling. The budget test was right:
+ * the four facts fit in a sentence, and a sentence is what a reader takes in
+ * anyway. The long form lives in `animationNote`, which fires at the moment the
+ * mistake is actually made.
+ */
+export function animationVocabulary() {
+    return (`config.animation is an OBJECT: { active: true, type: ${ANIMATION.types.join('|')}, ` +
+        `easing?: ${ANIMATION.easings.join('|')}, delay?, duration? }. active:true is REQUIRED ` +
+        '(a type alone is not consent), the type is UNDERSCORED, and it is base-only. Anything ' +
+        'else renders no animation at all, with no error.');
+}
+/**
+ * The warning for a `config.animation` write that will not animate.
+ *
+ * A WARNING rather than a refusal, for the reason `unknownValueNote` records:
+ * the platform STORES whatever it is given. But unlike a normalised string,
+ * every miss here renders NOTHING rather than something else — so the note says
+ * what will happen, not merely what the value is not.
+ */
+export function animationNote(value) {
+    const has = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+    const types = ANIMATION.types.join(', ');
+    if (!has(value)) {
+        return (`config.animation is an OBJECT, not a ${typeof value === 'string' ? 'string' : typeof value}: ` +
+            `{ active: true, type: "<one of ${types}>", easing, delay, duration }. The renderer reads it ` +
+            'as map[string]interface{}, so this value is the zero value and the node will not animate — ' +
+            'stored, saved and published with no error at any step.');
+    }
+    const notes = [];
+    if (value.active !== true) {
+        notes.push('active:true is missing, and a type alone is deliberately not consent — the panel keeps the ' +
+            'type when the switch goes off, so the renderer emits nothing without it');
+    }
+    const t = value.type;
+    if (typeof t !== 'string' || !ANIMATION.types.includes(t)) {
+        const near = typeof t === 'string' ? t.replace(/-/g, '_') : '';
+        notes.push(`type ${JSON.stringify(t)} is not one of ${types}` +
+            (near && ANIMATION.types.includes(near)
+                ? ` — the stored spelling uses UNDERSCORES, so you want "${near}"`
+                : '') +
+            '; an unrecognised type emits no keyframes and no rule');
+    }
+    const e = value.easing;
+    if (e !== undefined && (typeof e !== 'string' || !ANIMATION.easings.includes(e))) {
+        // The mild one: the animation still RUNS, wearing the wrong curve.
+        notes.push(`easing ${JSON.stringify(e)} is outside ${ANIMATION.easings.join(', ')}, so the renderer ` +
+            `uses "${ANIMATION.easingFallback}" — the animation runs, with a curve you did not choose`);
+    }
+    if (!notes.length)
+        return null;
+    return `config.animation will not do what this says. ${notes.join('. ')}.`;
+}

package/dist/server.js

@@ -13,6 +13,7 @@ import { registerLiveTools } from './tools/live.js';
 import { registerStoreTools } from './tools/store.js';
 import { registerImportTools } from './tools/importpage.js';
 import { registerUndoTools } from './tools/undo.js';
+import { registerThemeTools } from './tools/theme.js';
 /**
  * Sent on every handshake, so it is short, and says nothing a tool description
  * already says. Counts come from the generated source records, never literals.
@@ -70,6 +71,7 @@ export function createServer(ctx = buildContext()) {
     const pageSession = registerPageTools(server, ctx);
     registerLiveTools(server, ctx, pageSession);
     registerStoreTools(server, ctx);
+    registerThemeTools(server, ctx);
     registerImportTools(server, ctx, pageSession);
     registerUndoTools(server, ctx);
     return server;

package/dist/tools/importpage.js

@@ -464,7 +464,13 @@ export function registerImportTools(server, ctx, session) {
             }
         }
         const tokens = tokenDoc ? tokensFromPage(tokenDoc.doc) : {};
-        const shots = await captureMany(plan.pages.map((p) => p.url), { maxImages: max_images ?? 24, maxNodes: max_nodes ?? 300 });
+        const shots = await captureMany(plan.pages.map((p) => p.url), 
+        // 900, not 300. The old ceiling was chosen against marketing pages;
+        // a real shop's homepage is a different quantity — ttgshop.vn measured
+        // 9,829px of catalogue across a dozen collection bands, and 300 cut it
+        // off in the middle of the third. A cap is here to stop a runaway page,
+        // not to decide how much of an ordinary one survives.
+        { maxImages: max_images ?? 60, maxNodes: max_nodes ?? 900 });
         const byUrl = new Map(shots.map((s) => [s.url, s]));
         // ONE UPLOAD PER IMAGE FOR THE WHOLE SITE, not per page. A logo, a payment
         // strip and a footer badge appear on every page of a real site, and

package/dist/tools/page.js

@@ -8,7 +8,7 @@ import { baseOnlyNote } from '../domains/site/baseonly.js';
 import { detachNote, presetIdOf, presetLayer } from '../domains/site/theme.js';
 import { inertHintsFor } from '../domains/site/inert.js';
 import { hasSeed, seedDocument, seedSummary, seededTypes } from '../domains/site/storepage.js';
-import { unknownValueNote } from '../domains/site/vocabulary.js';
+import { animationNote, unknownValueNote } from '../domains/site/vocabulary.js';
 import { skinLevelNote } from '../domains/site/fieldskin.js';
 import { siteTheme } from '../domains/site/theme-fetch.js';
 import { request, redact } from '../transport/http.js';
@@ -520,10 +520,15 @@ export function registerPageTools(server, ctx) {
             if (e.namespace !== 'config')
                 continue;
             for (const [k, v] of Object.entries(e.keys)) {
-                const n = unknownValueNote(k, v);
+                // THE ENTRANCE ANIMATION IS ITS OWN QUESTION, because it is an object
+                // rather than a word and every way of missing it renders NOTHING
+                // rather than a normalised something. Keyed on the whole value: two
+                // nodes given the same wrong animation deserve one answer, and two
+                // given different wrong ones deserve two.
+                const n = k === 'animation' ? animationNote(v) : unknownValueNote(k, v);
                 if (!n)
                     continue;
-                const once = ctx.notices.once(`config-value:${k}=${String(v)}`, n);
+                const once = ctx.notices.once(`config-value:${k}=${JSON.stringify(v)}`, n);
                 if (once)
                     valueNotes.push(once);
             }

package/dist/tools/theme.js

@@ -0,0 +1,136 @@
+import { z } from 'zod';
+import { text } from '../mcp/response.js';
+import { request } from '../transport/http.js';
+import { siteToken } from './credentialpick.js';
+import { siteFor } from './context.js';
+import { STARTER_THEME } from '../domains/site/theme.js';
+/** The site's theme, or the starter when it has never saved one. */
+async function readTheme(ctx, siteId) {
+    const got = (await request({
+        base: ctx.base,
+        method: 'GET',
+        path: `/api/sites/${encodeURIComponent(siteId)}/theme`,
+        token: siteToken(ctx),
+        fetchImpl: ctx.fetchImpl,
+    }));
+    // A NEW SITE ANSWERS 200 {"theme": null} — the platform's own comment calls
+    // that "the NORMAL first-visit state, not a failure". Starting from the
+    // starter rather than from `{}` is what makes the first write store a
+    // COMPLETE theme instead of a palette with one token in it.
+    if (got?.theme && typeof got.theme === 'object')
+        return { theme: got.theme, origin: 'site' };
+    return { theme: structuredClone(STARTER_THEME), origin: 'starter' };
+}
+export function registerThemeTools(server, ctx) {
+    server.registerTool('sb_theme', {
+        description: "The site's palette and type scale — the layer every element's style preset resolves " +
+            'from, so one token repaints every page at once. Call it with nothing to read what the ' +
+            'site actually has. `colors` and `text_styles` PATCH the saved document: what you do not ' +
+            'name is kept.',
+        inputSchema: {
+            site_id: z.string().optional(),
+            colors: z
+                .record(z.string())
+                .optional()
+                .describe('Token id -> CSS colour, e.g. { "heading": "#2E2A3B", "primary": "#E8557A" }'),
+            text_styles: z
+                .record(z.record(z.string()))
+                .optional()
+                .describe('Text style slug -> base declarations, e.g. { "h1": { "fontSize": "48px" } }'),
+            dry_run: z.boolean().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, async ({ site_id: given, colors, text_styles, dry_run }) => {
+        const site_id = siteFor(ctx, given);
+        const { theme, origin } = await readTheme(ctx, site_id);
+        // READ. What the site actually paints from, which is what rule 0 wants
+        // before anything is decided.
+        if (!colors && !text_styles) {
+            return text({
+                origin: origin === 'site'
+                    ? 'this site, saved'
+                    : 'the STARTER theme — this site has never saved one, so this is what it renders ' +
+                        'with and what a first write would be built from',
+                version: theme.version,
+                colors: Object.fromEntries((theme.colors ?? []).map((c) => [c.id, c.value])),
+                text_styles: Object.fromEntries((theme.textStyles ?? []).map((t) => [t.slug, t.base ?? {}])),
+                schemes: (theme.schemes ?? []).map((s) => s.id),
+                presets: (theme.presets ?? []).length,
+                note: ctx.notices.once('theme_leverage', 'A style preset compiles to a class rule BENEATH a node\'s own values, so every node ' +
+                    'that has not been given a literal follows these tokens. Changing one here is the ' +
+                    'cheapest way to restyle a whole site — and a literal written with sb_set detaches ' +
+                    'that node from it permanently.'),
+            });
+        }
+        // PATCH. Unknown ids are REFUSED rather than added: a token nothing
+        // resolves from is a value the platform stores and no renderer reads,
+        // which is the silent-failure family this server exists to close — and a
+        // typo would land there rather than on the colour the caller meant.
+        const changes = [];
+        const known = new Set((theme.colors ?? []).map((c) => c.id));
+        const unknown = Object.keys(colors ?? {}).filter((id) => !known.has(id));
+        if (unknown.length) {
+            throw new Error(`sbuilder: no colour token named ${unknown.map((u) => JSON.stringify(u)).join(', ')} on ` +
+                `this site. Its tokens are: ${[...known].join(', ')}. Every style preset resolves ` +
+                'through these ids, so a new one would be stored and read by nothing.');
+        }
+        for (const [id, value] of Object.entries(colors ?? {})) {
+            const token = theme.colors.find((c) => c.id === id);
+            if (token.value === value)
+                continue;
+            changes.push({ what: `colors.${id}`, from: token.value, to: value });
+            token.value = value;
+        }
+        const slugs = new Set((theme.textStyles ?? []).map((t) => t.slug));
+        const badSlugs = Object.keys(text_styles ?? {}).filter((s) => !slugs.has(s));
+        if (badSlugs.length) {
+            throw new Error(`sbuilder: no text style named ${badSlugs.map((b) => JSON.stringify(b)).join(', ')} on ` +
+                `this site. Its slugs are: ${[...slugs].join(', ')}. A preset names a style by SLUG ` +
+                'and the compiled --wb-ts-<slug>-<prop> variables are built from it.');
+        }
+        for (const [slug, decls] of Object.entries(text_styles ?? {})) {
+            const style = theme.textStyles.find((t) => t.slug === slug);
+            style.base = style.base ?? {};
+            for (const [prop, value] of Object.entries(decls)) {
+                const before = style.base[prop] ?? '(unset)';
+                if (before === value)
+                    continue;
+                changes.push({ what: `textStyles.${slug}.${prop}`, from: before, to: value });
+                style.base[prop] = value;
+            }
+        }
+        if (!changes.length) {
+            return text({ unchanged: true, note: 'Every value named already holds that value.' });
+        }
+        // The document goes back WHOLE, so this can only ever be true — asserted
+        // anyway, because the one failure this endpoint cannot take back is a
+        // theme with nothing in it.
+        if (!theme.colors?.length || !theme.presets?.length) {
+            throw new Error('sbuilder: refusing to save a theme with no colours or no presets.');
+        }
+        if (dry_run !== false) {
+            return text({
+                dry_run: true,
+                would_change: changes,
+                on: site_id,
+                built_from: origin === 'site' ? "this site's saved theme" : 'the starter theme',
+                note: 'Nothing was sent. This is SITE-WIDE: every page, and every node that has not been ' +
+                    'given a literal of its own. Re-call with dry_run:false.',
+            });
+        }
+        await request({
+            base: ctx.base,
+            method: 'PUT',
+            path: `/api/sites/${encodeURIComponent(site_id)}/theme`,
+            token: siteToken(ctx),
+            body: { theme },
+            fetchImpl: ctx.fetchImpl,
+        });
+        return text({
+            changed: changes,
+            on: site_id,
+            next: 'Republish the pages that should show it — a theme is compiled into each page\'s ' +
+                'stylesheet, so a saved page keeps the old palette until it is published again.',
+        });
+    });
+}

package/dist/vision/capture.js

@@ -74,7 +74,16 @@ function capturePage(limits) {
         // nothing, so a contact page says it had one. The CONTROLS stay ignored —
         // a stray input outside a form is chrome, and the fields of a form that IS
         // reported are counted there rather than walked into.
-        'NAV', 'INPUT', 'SELECT', 'TEXTAREA', 'BUTTON',
+        //
+        // BUTTON IS NOT HERE EITHER, AND USED TO BE — filed with the form controls,
+        // on the reasoning that fits `input` and does not fit it. A `<button>` with
+        // words in it is a CALL TO ACTION, which on a shop is the most important
+        // interactive thing on the page: MEASURED on ttgshop.vn, 27 of them dropped
+        // in one capture, every "Mua ngay" and "Thêm vào giỏ" among them. A button
+        // that really is a form control is unreachable anyway — the FORM branch
+        // returns without walking its children — so the only ones this reaches are
+        // the ones a reader would press.
+        'NAV', 'INPUT', 'SELECT', 'TEXTAREA',
     ]);
     const forms = [];
     /** The provider and id behind an embed URL, or null if this platform has no element for it. */
@@ -136,6 +145,89 @@ function capturePage(limits) {
     // a throwaway tab that is closed straight after.
     for (const d of Array.from(document.querySelectorAll('details')))
         d.setAttribute('open', '');
+    // A TAB PANEL THAT IS NOT THE OPEN ONE MEASURES AS ZERO, and on a shop that
+    // is most of the page.
+    //
+    // Same principle as the `<details>` pass above and the same sentence decides
+    // it: the source's collapsed state is not content. MEASURED on ttgshop.vn —
+    // a homepage that lays its catalogue out in tabs (PC GAMING, WORKSTATION,
+    // AMD, MINI, …) — 73% of the page's own text was in panels carrying
+    // `display:none`, so the import kept one tab's products and silently dropped
+    // every other tab: product names, prices, discounts, stock. Nothing reported
+    // it, because a hidden element is indistinguishable from an absent one once
+    // it has been skipped.
+    //
+    // REVEALED BY THE SHAPE OF A PANEL SET, never by unhiding what is hidden. A
+    // `display:none` element with no visible SIBLING is a modal, a drop-down, an
+    // off-canvas menu or a mobile-only copy of a desktop bar — showing those is
+    // how an import grows a navigation drawer in the middle of a page. What marks
+    // a panel is that it sits beside a peer of the same kind that IS shown: one
+    // tab open, the rest waiting. So the reveal needs a visible sibling, real
+    // content of its own, and a parent that is not page chrome.
+    //
+    // The display value is COPIED from that visible sibling rather than forced to
+    // `block`: a flex row of cards revealed as a block would stack, and the walk
+    // reads `display` to decide what is a row.
+    const revealPanels = () => {
+        const parents = new Set();
+        for (const el of Array.from(document.querySelectorAll('[style*="display"], .hidden, [hidden], [aria-hidden]'))) {
+            const p = el.parentElement;
+            if (p)
+                parents.add(p);
+        }
+        // Any container can hold a panel set; the attribute scan above only finds
+        // the common spellings, so the sweep below is over every parent of more
+        // than one element, bounded by the document itself.
+        for (const el of Array.from(document.querySelectorAll('*'))) {
+            if (el.children.length > 1)
+                parents.add(el);
+        }
+        for (const parent of parents) {
+            if (inPageChrome(parent))
+                continue;
+            const kids = Array.from(parent.children);
+            if (kids.length < 2)
+                continue;
+            // A VISIBLE PEER IS NOT ENOUGH, and the first version of this stopped
+            // there — which reveals every hidden thing on the page, because anything
+            // in a content flow has visible siblings. A pinned test caught it: a
+            // `<p style="display:none">` beside a visible paragraph came back as
+            // content, and that `<p>` is hidden because its author hid it.
+            //
+            // A PANEL IS A CONTAINER THAT MATCHES ITS PEER. Same tag as a sibling
+            // that IS shown, and children of its own — which is what a tab body, a
+            // carousel track or a filtered grid always is, and what a hidden
+            // paragraph, a stray span and an empty slot never are.
+            const shownByTag = {};
+            const hidden = [];
+            for (const k of kids) {
+                const cs = getComputedStyle(k);
+                const r = k.getBoundingClientRect();
+                if (cs.display === 'none')
+                    hidden.push(k);
+                else if (!shownByTag[k.tagName] && r.width > 0 && r.height > 0) {
+                    shownByTag[k.tagName] = cs.display;
+                }
+            }
+            if (!hidden.length)
+                continue;
+            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.
+                // Low floor on purpose: a panel whose whole content is a price —
+                // "1.490.000 VNĐ", thirteen characters — is exactly the panel a shop
+                // hides, and a threshold tuned for prose skipped it.
+                const shownDisplay = shownByTag[k.tagName];
+                if (!shownDisplay || k.children.length === 0)
+                    continue;
+                const holds = clean(k.textContent).length > 2 || k.querySelectorAll('img').length > 0;
+                if (!holds)
+                    continue;
+                const was = k.getAttribute('style') ?? '';
+                k.setAttribute('style', `${was};display:${shownDisplay} !important`);
+            }
+        }
+    };
     /**
      * What the page CALLS this icon, in its own words. A candidate, never a verdict.
      *
@@ -145,6 +237,64 @@ function capturePage(limits) {
      * decides whether this platform has one by that name — nothing in the page can
      * answer that.
      */
+    /**
+     * THE REAL FILE, wherever the page put it — and on a shop that is almost never
+     * `src`.
+     *
+     * MEASURED on ttgshop.vn: 100 images, and 84 of them carry `data-src` with no
+     * `src` at all. Those 84 are the PRODUCT PHOTOS. Reading `src` alone imported
+     * a shop with a sixth of its pictures and reported the rest as
+     * `image-without-src`, which reads like the page's fault rather than ours.
+     *
+     * Lazy loading is not an edge case, it is how the web ships images: every
+     * mainstream loader (lazysizes, lozad, and most CMS themes) parks the URL in a
+     * data attribute and fills `src` only when the image nears the viewport — and
+     * a full-page screenshot does not scroll, which is the same reason `sb_look`
+     * walks the page before it fires.
+     *
+     * `srcset` is read for its LARGEST candidate rather than its first: the
+     * platform re-encodes what it is given, so handing it the 350w thumbnail when
+     * the page also offers 1400w throws away detail nothing can recover. A
+     * `data:` URI is refused wherever it appears — it is the 1x1 placeholder the
+     * loader is displaying until the real one arrives, which is precisely the
+     * placeholder this import must not ship.
+     */
+    const LAZY_SRC = ['data-src', 'data-original', 'data-lazy-src', 'data-lazy', 'data-echo', 'data-url'];
+    const widest = (srcset) => {
+        let best = '';
+        let bestW = -1;
+        for (const part of srcset.split(',')) {
+            const bits = part.trim().split(/\s+/);
+            if (!bits[0])
+                continue;
+            const w = /^([0-9]+)w$/.exec(bits[1] ?? '');
+            const n = w ? Number(w[1]) : 0;
+            if (n >= bestW) {
+                bestW = n;
+                best = bits[0];
+            }
+        }
+        return best;
+    };
+    const realSrc = (el) => {
+        const direct = el.getAttribute('src');
+        if (direct && !direct.startsWith('data:'))
+            return direct;
+        for (const a of LAZY_SRC) {
+            const v = el.getAttribute(a);
+            if (v && !v.startsWith('data:'))
+                return v;
+        }
+        for (const a of ['srcset', 'data-srcset']) {
+            const v = el.getAttribute(a);
+            if (v) {
+                const w = widest(v);
+                if (w && !w.startsWith('data:'))
+                    return w;
+            }
+        }
+        return '';
+    };
     const iconName = (el) => {
         const use = Array.from(el.querySelectorAll('use'))[0];
         const ref = use ? use.getAttribute('href') ?? use.getAttribute('xlink:href') : null;
@@ -385,8 +535,8 @@ function capturePage(limits) {
                 return [{ kind: 'heading', level: Number(tag.slice(1)), text }];
             }
             if (tag === 'IMG') {
-                const src = el.getAttribute('src');
-                if (!src || src.startsWith('data:')) {
+                const src = realSrc(el);
+                if (!src) {
                     skip('image-without-src');
                     return [];
                 }
@@ -398,6 +548,31 @@ function capturePage(limits) {
                 taken.nodes++;
                 return [{ kind: 'image', src: abs(src), alt: clean(el.getAttribute('alt')) }];
             }
+            if (tag === 'BUTTON') {
+                // Read exactly as an `<a>` is, minus the href: painted is a call to
+                // action, unpainted is a plain control, and the variant is what stops
+                // every one of them arriving as a pink pill — the defect the anchor
+                // branch below records from a documentation sidebar.
+                const text = clean(el.textContent);
+                // A BUTTON WITH MARKUP INSIDE IT IS A CARD, not a label — the same
+                // reading the anchor branch below already applies, and taking the text
+                // whole instead COST coverage rather than gaining it: a product tile
+                // wrapped in a `<button>` came back as one run-on string with the name,
+                // the price and the discount glued together, replacing three nodes that
+                // had been captured separately. Measured: 89.7% down to 82.7% on
+                // ttgshop.vn, recovered by descending first.
+                if (el.children.length > 0) {
+                    const inner = walkChildren(el);
+                    if (inner.length > 0)
+                        return inner;
+                }
+                if (!text) {
+                    skip('button-without-words');
+                    return [];
+                }
+                taken.nodes++;
+                return [{ kind: 'button', variant: looksLikeButton(el) ? 'cta' : 'link', text }];
+            }
             if (tag === 'A') {
                 const text = clean(el.textContent);
                 // A LINK THAT IS NOT A BUTTON IS STILL A LINK. It used to contribute
@@ -526,7 +701,20 @@ function capturePage(limits) {
                 // wrapping it — so the honest translation is the stack it already reads
                 // as. Twelve is above any real row seen here and far below a content
                 // grid.
-                const ROW_MAX = 12;
+                // THE CAP IS ABOUT SLIVERS, so it belongs on the containers that make
+                // them. A NOWRAP row divides one width by its column count — that is
+                // how 279 columns became 279 slivers — but a container that WRAPS never
+                // does: it lays out as many as fit and starts a new line, which is the
+                // same thing a twenty-card product shelf wants and exactly what the
+                // source was already showing.
+                //
+                // Twelve on a wrapping shelf was a rule coercing the layout rather than
+                // reading it: a shop's collection band came back as a vertical stack of
+                // cards because it had more than a dozen. The bound that remains is the
+                // whole-import node budget, which is the honest place for "this page is
+                // enormous".
+                const wraps = grid || cs.flexWrap === 'wrap';
+                const ROW_MAX = wraps ? 60 : 12;
                 if (lays && row && kids.length >= 2 && kids.length <= ROW_MAX) {
                     taken.nodes++;
                     return [{
@@ -535,7 +723,7 @@ function capturePage(limits) {
                             // A GRID ALWAYS WRAPS — that is what a grid IS — and `flexWrap` reads
                             // `nowrap` on one because the property does not apply. Carrying that
                             // literally gave the columns nowhere to go at any width.
-                            wrap: grid || cs.flexWrap === 'wrap',
+                            wrap: wraps,
                             children: kids,
                         }];
                 }
@@ -561,6 +749,12 @@ function capturePage(limits) {
         };
         return walk(root);
     };
+    // AFTER `inPageChrome` exists, and that ordering is load-bearing: the reveal
+    // asks whether a container is page chrome, and a `const` arrow read before
+    // its own definition throws inside `evaluate`, which kills the whole capture.
+    // The same class as the closure trap this file already carries — a name that
+    // exists but is not yet initialised.
+    revealPanels();
     // SECTION CANDIDATES, widest first: a page that marks its bands up
     // semantically is read that way, and one that does not falls back to the
     // top-level children of its main content, which is what a hand-written page
@@ -614,15 +808,119 @@ function capturePage(limits) {
         return acc;
     };
     let sections = build(candidates);
-    // THE FALLBACK HAS TO FIRE ON AN EMPTY RESULT, not only on an empty candidate
-    // LIST. A page can offer `<section>` elements that hold nothing this platform
-    // renders — a wrapper around a canvas, a slot filled by script later — and the
-    // old order took "we found candidates" as "we found content", so the whole
-    // page came back empty. Measured: tailwindcss.com kept 0 of 6,004 characters
-    // while reporting one skipped empty section.
-    if (sections.length === 0) {
+    // THE FALLBACK HAS TO FIRE ON A DERISORY RESULT, not only on an empty one —
+    // and this entry has now been widened TWICE, each time by a real page.
+    //
+    // First it fired only on an empty candidate LIST, so a page offering
+    // `<section>`s that hold nothing this platform renders came back empty
+    // (tailwindcss.com: 0 of 6,004 characters, one skipped empty section). That
+    // was fixed by firing on an empty RESULT.
+    //
+    // An empty result is still the wrong test, because it treats "we captured
+    // something" as "we captured the page". MEASURED on ttgshop.vn, a shop with
+    // 2,856 divs, 602 paragraphs, 110 headings and 100 images: the whole page
+    // lives in `div.homepage`, and the document's only two `<section>` elements
+    // are a BREADCRUMB and one more. The selector privileges `<section>`
+    // absolutely, so the breadcrumb WAS the result — one section, one text node,
+    // 34 of 4,993 characters — and because that is not empty, nothing fell back.
+    // A shop imported as its own breadcrumb, with no error at any step.
+    //
+    // So the question is coverage, against the denominator this file already
+    // records as the honest one: page chrome is skipped ON PURPOSE and must not
+    // count against the result, or every correct import of a nav-heavy site would
+    // look like a failure. Below half of the non-chrome text, the candidate set
+    // was simply the wrong reading of the page, and the body walk is tried and
+    // kept only if it does better — so a page where the sections really are the
+    // content pays one comparison and keeps its own answer.
+    const textOf = (nodes) => {
+        let n = 0;
+        const walk = (c) => {
+            if (typeof c.text === 'string')
+                n += c.text.length;
+            for (const k of c.children ?? [])
+                walk(k);
+        };
+        for (const c of nodes)
+            walk(c);
+        return n;
+    };
+    let chromeChars = 0;
+    for (const el of Array.from(document.querySelectorAll('header, nav, footer'))) {
+        if (inPageChrome(el))
+            chromeChars += (el.innerText ?? '').length;
+    }
+    const contentChars = Math.max(0, (document.body.innerText ?? '').length - chromeChars);
+    // NO SIZE FLOOR ON THE CHECK. An earlier version only asked the question on
+    // pages with more than 400 characters, which is the guard you write when you
+    // fear a fallback firing too often — but the fallback cannot do harm here: it
+    // BUILDS the alternative and keeps it only if it captured more, so the worst
+    // case is one wasted walk on a page that was already right. A small page is
+    // also exactly where one stray band is the whole import.
+    if (sections.length === 0 || (contentChars > 0 && textOf(sections) < contentChars * 0.5)) {
+        // THE CONTENT ROOT, not `body` — otherwise the whole page comes back as ONE
+        // band and every arrangement the source had is gone. Measured on
+        // ttgshop.vn: `body` yields `div.homepage`, one candidate holding 9,829px of
+        // shop, so the import produced a single section with 467 text nodes in it.
+        //
+        // A real page wraps its content two or three deep before the bands start
+        // (`body > div.homepage > div.container > div.section-collection…`), so the
+        // root is found by DESCENDING while one child still holds nearly all the
+        // text. That child is a wrapper by definition — it has siblings that are
+        // scripts, chrome and empty slots — and its children are the bands.
+        // Bounded, and it stops the moment the text spreads out, which is exactly
+        // when the bands have been reached.
+        const textLen = (el) => (el.innerText ?? el.textContent ?? '').length;
+        let root = document.querySelectorAll('main')[0] ?? document.body;
+        for (let depth = 0; depth < 6; depth += 1) {
+            const kids = Array.from(root.children).filter((k) => !inPageChrome(k));
+            if (kids.length === 0)
+                break;
+            const total = textLen(root);
+            let biggest = kids[0];
+            for (const k of kids)
+                if (textLen(k) > textLen(biggest))
+                    biggest = k;
+            if (total < 200 || textLen(biggest) < total * 0.7)
+                break;
+            root = biggest;
+        }
+        // BOTH READINGS, AND THE ONE THAT COVERS MORE WINS. Descending finds the
+        // band split on a page that wraps its content; it LOSES material on a page
+        // whose content is spread across two wrappers, because everything outside
+        // the biggest one is left behind — measured here as 89.7% falling to 82.7%.
+        // Neither rule is right for every page and the comparison costs one walk,
+        // so the page decides rather than the heuristic.
+        // A SPECULATIVE BUILD MUST LEAVE NO TRACE, and the first version of this
+        // left three. `build` is not pure — it pushes every `<form>` it meets onto
+        // the shared list, counts every skip, and spends the image and node budget
+        // — so trying a second reading REPORTED a one-form page as having three and
+        // trebled every skip count. Caught by two tests that were already there,
+        // which is the argument for asserting side effects and not only results.
+        const snap = () => ({
+            forms: forms.length,
+            skipped: { ...skipped },
+            taken: { ...taken },
+        });
+        const restore = (was) => {
+            forms.length = was.forms;
+            for (const k of Object.keys(skipped))
+                delete skipped[k];
+            Object.assign(skipped, was.skipped);
+            taken.images = was.taken.images;
+            taken.nodes = was.taken.nodes;
+        };
+        const before = snap();
+        let bestState = snap();
         const main = document.querySelectorAll('main')[0] ?? document.body;
-        sections = build(Array.from(main.children));
+        for (const from of [root, main]) {
+            restore(before);
+            const wider = build(Array.from(from.children));
+            if (textOf(wider) > textOf(sections)) {
+                sections = wider;
+                bestState = snap();
+            }
+        }
+        restore(bestState);
     }
     const link = Array.from(document.querySelectorAll('link[rel="canonical"]'))[0];
     const canonical = link ? (link.getAttribute('href') ?? '') : '';

package/package.json

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