sbuilder-mcp 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -6,6 +6,16 @@ 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

package/CHANGELOG.vi.md

@@ -6,6 +6,16 @@ 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

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

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