sbuilder-mcp 0.28.0 → 0.30.0

package/CHANGELOG.md

@@ -6,6 +6,25 @@ 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.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
+- sb_media_upload's `pick` argument now accepts several ids at once, so stocking a new site's empty library from one search result takes one upload call instead of one per photo; a picked id the search did not return refuses the whole call rather than uploading part of it.
+- A layout pattern now declares how many picture slots it has, and sb_template_use reports how many the site's library could fill and names the sb_media_upload calls (query, then pick with several ids) that fill the rest.
+
+### Changed
+- sb_template_use's result field for a library with too few images is now `pictures`, naming the exact shortfall (slots wanted vs. images offered) instead of the old `images` field, which only ever said the library was completely empty.
+
 ## [0.28.0] - 2026-09-10
 
 ### Added

package/CHANGELOG.vi.md

@@ -6,6 +6,25 @@ 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.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
+- Tham số `pick` của sb_media_upload giờ nhận nhiều id cùng lúc, nên việc lấp đầy thư viện trống của một site mới từ một lần tìm kiếm chỉ cần một lệnh upload thay vì một lệnh cho mỗi ảnh; một id được chọn mà kết quả tìm kiếm không trả về sẽ từ chối toàn bộ lệnh thay vì chỉ upload một phần.
+- Một layout dựng sẵn giờ khai báo số ô chứa ảnh nó có, và sb_template_use báo lại thư viện của site lấp được bao nhiêu ô cùng tên các lệnh sb_media_upload (query, rồi pick với nhiều id) để lấp phần còn lại.
+
+### Changed
+- Trường kết quả của sb_template_use khi thư viện thiếu ảnh giờ là `pictures`, nêu đúng phần còn thiếu (số ô cần vs. số ảnh có) thay cho trường `images` cũ, vốn chỉ báo khi thư viện hoàn toàn trống.
+
 ## [0.28.0] - 2026-09-10
 
 ### Added

package/README.md

@@ -101,13 +101,14 @@ in this client: one would put the very key the platform exists to hold back into
 | `sb_publish` | Compile the draft into the live page (cascades to shared globals) |
 | `sb_review` | Every defect a visitor would see, each with its fix, plus the five gaps between this store and a paid order |
 | `sb_media_list` | The site's media library |
-| `sb_media_upload` | Add an image and get its URL — a local path, a URL the platform fetches, or a SEARCH for real photographs you read and pick from |
+| `sb_media_upload` | Add an image and get its URL — a local path, a URL the platform fetches, or a SEARCH for real photographs you read and pick from, one or several at a time |
 | `sb_live_join` | Join the editor's live-edit room as a visible peer — edits then appear live |
 | `sb_look` | Save, render, and return screenshots plus measured node boxes and layout defects measured on the render |
 | `sb_event` | Give a node a click action — open the cart, go to a page, open a pop-up |
 | `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

@@ -98,13 +98,14 @@ nhét ngược lại vào mọi bản cài.
 | `sb_publish` | Biên dịch bản nháp thành trang live (lan sang global dùng chung) |
 | `sb_review` | Mọi khiếm khuyết người xem sẽ thấy, kèm lệnh sửa từng cái, và năm khoảng trống chắn giữa cửa hàng với một đơn đã thanh toán |
 | `sb_media_list` | Thư viện ảnh của site |
-| `sb_media_upload` | Thêm ảnh và lấy URL — file trên máy, một URL để nền tảng tự tải, hoặc TÌM ảnh chụp thật để đọc mô tả rồi chọn |
+| `sb_media_upload` | Thêm ảnh và lấy URL — file trên máy, một URL để nền tảng tự tải, hoặc TÌM ảnh chụp thật để đọc mô tả rồi chọn, một hoặc nhiều tấm một lượt |
 | `sb_live_join` | Vào phòng live-edit của editor như một peer nhìn thấy được — sửa gì hiện ngay |
 | `sb_look` | Lưu, render, trả về ảnh chụp kèm box đo được của node và lỗi bố cục đo trên bản render |
 | `sb_event` | Gắn click action cho một node — mở giỏ, sang trang, mở pop-up |
 | `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/patterns.js

@@ -93,6 +93,7 @@ export const LAYOUT_PATTERNS = [
         id: 'sb_hero_split',
         name: 'Hero — hai cột',
         use: 'Mở đầu trang: tiêu đề, một câu, nút hành động bên trái; chỗ cho ảnh bên phải',
+        images: 1,
         build: (t, pool) => {
             const used = new Set();
             return section([
@@ -149,6 +150,7 @@ export const LAYOUT_PATTERNS = [
     {
         id: 'sb_gallery',
         name: 'Dải ảnh',
+        images: 6,
         use: 'Một hàng ảnh cuốn dòng, lấy từ thư viện ảnh của chính site',
         build: (t, pool) => {
             const used = new Set();

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/live.js

@@ -405,14 +405,18 @@ export function registerLiveTools(server, ctx, session) {
     server.registerTool('sb_media_upload', {
         description: 'Put an image into the media library and get its URL back, ready for sb_set. Takes a ' +
             'local path, a URL, or a SEARCH — `query` returns real photographs with their own ' +
-            'descriptions, and `pick` uploads the one you chose. The only way to add an image.',
+            'descriptions, and `pick` uploads the one you chose, or several at once to stock a ' +
+            'site you just built. The only way to add an image.',
         inputSchema: {
             site_id: z.string().optional(),
             path: z.string().optional().describe('A file on this machine'),
             url: z.string().optional().describe('Fetched, then uploaded'),
             query: z.string().optional().describe('Search real photographs; read the descriptions, then pick'),
             orientation: z.enum(['landscape', 'portrait', 'square']).optional(),
-            pick: z.number().int().optional().describe('The id of the search result to upload'),
+            pick: z
+                .union([z.number().int(), z.array(z.number().int())])
+                .optional()
+                .describe('The id of the search result to upload — or several ids, which stocks a site in one call'),
             name: z.string().optional(),
             folder_id: z.string().optional(),
             dry_run: z.boolean().optional(),
@@ -446,48 +450,106 @@ export function registerLiveTools(server, ctx, session) {
                 }
                 throw e;
             }
-            const chosen = pick !== undefined ? photos.find((p) => p.id === pick) : undefined;
-            if (!chosen) {
+            // STOCKING A SITE IS WHY THIS TAKES SEVERAL. One search answers with
+            // eight photographs and a gallery band wants six of them — and a site
+            // this server has just built has an EMPTY library, so every picture
+            // slot in every pattern is a sentence until somebody fills it. One
+            // pick per call made that twelve round trips for one band, which is
+            // how a correct rule becomes a rule nobody follows.
+            //
+            // It does NOT weaken rule 7. What that rule protects is that somebody
+            // LOOKED: reading eight descriptions and choosing six is the same act
+            // of choosing as reading eight and choosing one. What it forbids is
+            // uploading a hit nobody read, and no `pick` still uploads nothing.
+            const wanted = pick === undefined ? [] : Array.isArray(pick) ? pick : [pick];
+            const chosen = wanted
+                .map((id) => photos.find((p) => p.id === id))
+                .filter((p) => p !== undefined);
+            const absent = wanted.filter((id) => !photos.some((p) => p.id === id));
+            // A PARTIAL PICK IS REFUSED WHOLE rather than half-uploaded. The caller
+            // named a set; delivering some of it and reporting the rest as a note
+            // leaves them to work out which slots they can still fill.
+            if (chosen.length === 0 || absent.length > 0) {
                 return text({
-                    ...(pick !== undefined ? { no_such_pick: pick } : {}),
+                    ...(absent.length === 1 ? { no_such_pick: absent[0] } : {}),
+                    ...(absent.length > 1 ? { no_such_picks: absent } : {}),
                     found: photos.map((p) => ({
                         pick: p.id,
                         shows: p.alt || '(the photographer left no description)',
                         size: `${p.width}x${p.height}`,
                         by: p.photographer,
                     })),
-                    next: 'Read what each one SHOWS, then re-call with pick:<id> and dry_run:false. The photo ' +
-                        "is uploaded into this site's own library, never hotlinked.",
+                    next: 'Read what each one SHOWS, then re-call with pick:<id> and dry_run:false — or ' +
+                        'pick:[<id>,<id>,…] to take several in one call, which is what fills a gallery ' +
+                        "band. Each photo is uploaded into this site's own library, never hotlinked.",
                     licence: ctx.notices.once('stock_licence', 'These are Pexels photographs: free for commercial use, with attribution ' +
                         'appreciated rather than required, so a storefront can carry one without printing ' +
                         'a credit line nobody asked for. The photographer comes back with each result if ' +
                         'you want to credit anyway.'),
                 });
             }
+            // ONE PICK KEEPS THE SHAPE IT HAS ALWAYS HAD. A caller that asked for
+            // one photograph gets one answer about one photograph; only a caller
+            // that asked for several is handed a list to read.
+            const solo = chosen.length === 1 ? chosen[0] : undefined;
             if (dry_run !== false) {
                 return text({
                     dry_run: true,
-                    would_upload: chosen.url,
-                    shows: chosen.alt,
-                    by: chosen.photographer,
+                    would_upload: solo ? solo.url : chosen.map((c) => c.url),
+                    shows: solo ? solo.alt : chosen.map((c) => c.alt),
+                    by: solo ? solo.photographer : chosen.map((c) => c.photographer),
                     into: site_id,
                     note: 'Nothing was sent. Re-call with dry_run:false to upload.',
                 });
             }
-            const asset = await uploadMedia(ctx, site_id, {
-                url: chosen.url,
-                // THE DESCRIPTION BECOMES THE NAME, so the library is searchable by
-                // what the photographs show and the alt on the page means something.
-                name: name ?? chosen.alt ?? undefined,
-                folderId: folder_id,
-            });
+            // NOT ATOMIC, AND IT MUST NOT PRETEND TO BE. Each photo is its own
+            // upload, so the fifth failing does not un-upload the four that
+            // landed — throwing here would leave the caller with four images in
+            // the library, no idea which, and an error that names none of them.
+            // The same reasoning `sb_import_site` records for its per-page report.
+            const uploaded = [];
+            const failed = [];
+            for (const one of chosen) {
+                try {
+                    const asset = await uploadMedia(ctx, site_id, {
+                        url: one.url,
+                        // THE DESCRIPTION BECOMES THE NAME, so the library is searchable
+                        // by what the photographs show and the alt on the page means
+                        // something. A caller-supplied name can only speak for ONE photo,
+                        // so it is honoured only when one was picked.
+                        name: (solo ? name : undefined) ?? one.alt ?? undefined,
+                        folderId: folder_id,
+                    });
+                    uploaded.push({
+                        asset,
+                        shows: one.alt,
+                        credit: { by: one.photographer, profile: one.photographer_url, photo: one.page_url },
+                    });
+                }
+                catch (e) {
+                    failed.push({ pick: one.id, why: e.message });
+                }
+            }
+            if (solo) {
+                const only = uploaded[0];
+                if (!only)
+                    throw new Error(`sbuilder: ${failed[0]?.why ?? 'the upload failed'}`);
+                const asset = only.asset;
+                return text({
+                    asset,
+                    shows: solo.alt,
+                    credit: only.credit,
+                    next: asset.url
+                        ? `Use it: sb_set id "<node>", namespace specials, keys { "src": ${JSON.stringify(asset.url)} }`
+                        : 'Uploaded, but the server returned no url — read it back with sb_media_list.',
+                });
+            }
             return text({
-                asset,
-                shows: chosen.alt,
-                credit: { by: chosen.photographer, profile: chosen.photographer_url, photo: chosen.page_url },
-                next: asset.url
-                    ? `Use it: sb_set id "<node>", namespace specials, keys { "src": ${JSON.stringify(asset.url)} }`
-                    : 'Uploaded, but the server returned no url — read it back with sb_media_list.',
+                uploaded,
+                ...(failed.length ? { failed } : {}),
+                next: `${uploaded.length} in this site's library now. A layout pattern reads the library ` +
+                    'when it builds, so sb_template_use will put these into its picture slots — or set ' +
+                    'one on a node directly with sb_set namespace specials, keys { "src": "<url>" }.',
             });
         }
         if (!path && !url) {

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);
             }
@@ -794,6 +799,7 @@ export function registerPageTools(server, ctx) {
                     into: page_id,
                     tokens_from: fromTheme ? "this site's theme — the page has no look of its own yet" : 'this page',
                     images_available: pool.length,
+                    ...(pattern.images ? { pictures_wanted: pattern.images } : {}),
                     note: 'Composed against THIS page\'s tokens, not copied — the same heading ink, button ' +
                         'fill and section padding the page already uses. Pass dry_run:false to add it.',
                 });
@@ -805,11 +811,19 @@ export function registerPageTools(server, ctx) {
                 nodes: ids.length,
                 into: page_id,
                 rev: doc.rev,
-                ...(pool.length === 0
+                // A SHORT LIBRARY IS THE ORDINARY STATE OF A SITE THIS SERVER BUILT,
+                // not an edge case — nothing has been uploaded yet, so every picture
+                // slot in every pattern is a sentence. Saying "there are no images"
+                // and stopping leaves the agent to rediscover the fix; saying how
+                // many this band wanted and naming the two calls that fill them is
+                // the same fact with the next step attached.
+                ...(pattern.images && pool.length < pattern.images
                     ? {
-                        images: 'This site has no images in its library, so any picture slot in this band says ' +
-                            'so in words rather than showing a grey box. sb_media_upload takes a URL and ' +
-                            'the platform fetches it server-side.',
+                        pictures: `This band has ${pattern.images} picture slot${pattern.images > 1 ? 's' : ''} and the ` +
+                            `library offered ${pool.length}; the rest say so in words rather than showing a grey ` +
+                            'box. Fill them: sb_media_upload query:"<what the band should show>" reads back real ' +
+                            'photographs with their own descriptions, then pick:[…] uploads the ones you chose in ' +
+                            'one call. Re-run this pattern afterwards and it takes them.',
                     }
                     : {}),
                 ...(fromTheme

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/package.json

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