sbuilder-mcp 0.22.1 → 0.23.1

package/CHANGELOG.md

@@ -6,6 +6,23 @@ 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.23.1] - 2026-09-10
+
+### Added
+- sb_media_upload now asks the platform to fetch a URL source itself (`POST /api/media/{siteId}/from-url`) before falling back to downloading and re-uploading the bytes, so the file makes one network hop instead of two and its content type comes from the origin's own answer instead of being guessed from a header or extension.
+
+### Changed
+- sb_media_upload now raises rather than working around it when the platform refuses a URL source as `remote_blocked` (an address outside the public internet, such as a private range or the cloud metadata endpoint), since fetching that same URL from this server's own machine would defeat the platform's guard rather than respect it.
+
+### Fixed
+- sb_media_upload now reports the platform's own reason when it cannot reach a URL source (for example, "www.blender.org answered 404") instead of the generic "the platform could not read it".
+
+## [0.23.0] - 2026-09-10
+
+### Added
+- sb_templates now lists six built-in layout patterns (two hero variants, a feature trio, a stats row, a CTA band, and an FAQ) under `built_in`, alongside the site's own saved section templates, so a page can start from a designed composition instead of an invented one.
+- sb_template_use can now instantiate a built-in layout by id: the section is composed against the target page's own tokens (heading color, button fill, section padding) instead of being copied verbatim, and falls back to the site's theme tokens, carried as `var(--wb-color-…)`, when the page has no look of its own yet.
+
 ## [0.22.1] - 2026-09-10
 
 ### Fixed

package/CHANGELOG.vi.md

@@ -6,6 +6,23 @@ 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.23.1] - 2026-09-10
+
+### Added
+- sb_media_upload giờ yêu cầu chính nền tảng tải nguồn URL trước (`POST /api/media/{siteId}/from-url`) rồi mới lùi về cách cũ là tải xuống rồi upload lại, nên file chỉ đi một chặng mạng thay vì hai, và content type được lấy từ câu trả lời của chính nguồn thay vì đoán từ header hay phần mở rộng.
+
+### Changed
+- sb_media_upload giờ báo lỗi thay vì tìm cách lách khi nền tảng từ chối một nguồn URL với mã `remote_blocked` (địa chỉ không thuộc internet công khai, như dải private hoặc endpoint metadata của cloud), vì việc tự tải URL đó từ máy chạy server này sẽ phá vỡ lớp bảo vệ của nền tảng thay vì tuân theo nó.
+
+### Fixed
+- sb_media_upload giờ báo đúng lý do của chính nền tảng khi không tải được một nguồn URL (ví dụ "www.blender.org answered 404") thay vì thông báo chung "the platform could not read it".
+
+## [0.23.0] - 2026-09-10
+
+### Added
+- sb_templates giờ liệt kê sáu layout dựng sẵn (hai kiểu hero, ba lợi ích, dải số liệu, dải kêu gọi hành động và FAQ) trong `built_in`, cùng với các section template đã lưu của chính site, để một trang có thể bắt đầu từ một bố cục được thiết kế thay vì tự bịa ra.
+- sb_template_use giờ có thể thả một layout dựng sẵn theo id: section được soạn theo token của chính trang đích (màu chữ tiêu đề, nền nút, padding section) thay vì được copy nguyên văn, và lấy theo token theme của site, mang dạng `var(--wb-color-…)`, khi trang chưa có phong cách riêng.
+
 ## [0.22.1] - 2026-09-10
 
 ### Fixed

package/README.md

@@ -86,7 +86,7 @@ make, because those mean "this person's account".
 | `sb_move` | Move a node to another parent |
 | `sb_remove` | Remove a node and its subtree |
 | `sb_duplicate` | Copy a node and its subtree under fresh ids, right after the original |
-| `sb_templates` | The store's saved section templates — designed sections to start from |
+| `sb_templates` | The store's saved section templates, plus the BUILT-IN layouts — hero, feature trio, stats, FAQ, CTA band — composed against the page's own tokens |
 | `sb_template_use` | Instantiate a template into a page |
 | `sb_page_list` | Every page on the site |
 | `sb_page_create` | Create a page — a store type arrives with the editor's own starting document; `type` is the route for checkout, product, category, post, course |

package/README.vi.md

@@ -83,7 +83,7 @@ là "tài khoản của người này".
 | `sb_move` | Chuyển node sang cha khác |
 | `sb_remove` | Xoá node và cả cây con |
 | `sb_duplicate` | Nhân bản một node và cả cây con dưới id mới, ngay sau bản gốc |
-| `sb_templates` | Section template đã lưu của cửa hàng — section thiết kế sẵn để bắt đầu |
+| `sb_templates` | Section template đã lưu của cửa hàng, cộng bộ layout DỰNG SẴN — hero, ba lợi ích, số liệu, FAQ, dải kêu gọi — soạn theo token của chính trang |
 | `sb_template_use` | Thả một template vào trang |
 | `sb_page_list` | Mọi trang của site |
 | `sb_page_create` | Tạo một trang — trang cửa hàng sinh ra đã có sẵn tài liệu như trong editor; `type` là đường đi cho checkout, product, category, post, course |

package/dist/domains/site/importmap.js

@@ -294,6 +294,23 @@ function one(c, t) {
             const kids = (c.children ?? []).map((k) => one(k, t)).filter((n) => n !== null);
             if (kids.length === 0)
                 return null;
+            // A COLUMN IS A STACK, NOT A ROW, and this was read by nothing.
+            //
+            // The capture never emits one — a column is what a page already is, so it
+            // is flattened in the browser — and `direction` sat in `Captured` unread
+            // for exactly that reason. The moment a caller composes a tree by hand
+            // (a layout pattern, a design ported out of Figma or Stitch) that stops
+            // being true, and every column it asked for came back as a row: a hero's
+            // heading, its sentence and its button side by side instead of stacked.
+            if (c.direction === 'column') {
+                if (kids.length === 1)
+                    return kids[0];
+                return {
+                    type: 'flex-block',
+                    style: { width: '100%', display: 'flex', flexDirection: 'column', gap: '12px' },
+                    children: kids,
+                };
+            }
             if (kids.length === 1)
                 return kids[0];
             // A ROW OF TWO OR MORE COLUMNS NEEDS AN EXPLICIT STACK BREAKPOINT, and

package/dist/domains/site/patterns.js

@@ -0,0 +1,130 @@
+import { toSpecs } from './importmap.js';
+/**
+ * THE LOOK A PAGE HAS BEFORE IT HAS ANYTHING, and it is not nothing.
+ *
+ * Rule 0 says read the page's own pattern. A blank page has none — and the next
+ * authority is not invention, it is the SITE'S THEME, which is where every
+ * element's style preset resolves from anyway.
+ *
+ * Written as `var(--wb-color-…)` rather than as the hex those resolve to, which
+ * is the whole point: a literal on a node OUTRANKS the preset beneath it
+ * permanently, so a pattern that baked today's `#171717` in would stop following
+ * the theme the moment the merchant changed it — the exact detachment this repo
+ * already records for imported icons. The variable is what the theme's own
+ * scheme roles use.
+ */
+export const THEME_TOKENS = {
+    headingColor: 'var(--wb-color-heading)',
+    textColor: 'var(--wb-color-text)',
+    buttonBg: 'var(--wb-color-primary)',
+    buttonColor: '#ffffff',
+};
+/** One section, through the same mapper an import goes through. */
+function section(children, t, style, innerStyle) {
+    const [spec] = toSpecs([{ kind: 'section', children }], t);
+    if (!spec)
+        return null;
+    const outer = style ? { ...spec, style: { ...spec.style, ...style } } : spec;
+    if (!innerStyle)
+        return outer;
+    // THE SECTION CENTRES ITS BLOCK; THE BLOCK CENTRES ITS CHILDREN. `textAlign`
+    // moves the words and leaves a `width: fit-content` button where it was, so a
+    // centred band came out with its call to action against the left margin.
+    const [inner, ...rest] = outer.children ?? [];
+    if (!inner)
+        return outer;
+    return {
+        ...outer,
+        children: [{ ...inner, style: { ...inner.style, ...innerStyle } }, ...rest],
+    };
+}
+const row = (children, wrap = false) => ({
+    kind: 'group',
+    direction: 'row',
+    wrap,
+    children,
+});
+const h = (text, level = 2) => ({ kind: 'heading', level, text });
+const p = (text) => ({ kind: 'text', text });
+const cta = (text, href = '#') => ({ kind: 'button', variant: 'cta', text, href });
+const img = (alt) => ({
+    // A PLACEHOLDER WITH NO SRC IS DROPPED by the mapper, which is right — an
+    // empty frame is not content. So a pattern that wants a picture says so in
+    // words and the caller points sb_set at it, rather than the page shipping a
+    // grey box nobody chose.
+    kind: 'image',
+    src: '',
+    alt,
+});
+/**
+ * The set. Deliberately small and deliberately ordinary: these are the bands
+ * every commercial page is built from, and a library that tried to be clever
+ * would be a library nobody could predict.
+ */
+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',
+        build: (t) => section([
+            row([
+                { kind: 'group', direction: 'column', children: [h('Tiêu đề chính', 1), p('Một câu nói rõ bạn bán gì và cho ai.'), cta('Mua ngay')] },
+                { kind: 'group', direction: 'column', children: [p('Đặt ảnh vào đây — sb_add một image, hoặc sb_set src lên khối này.')] },
+            ]),
+        ], t),
+    },
+    {
+        id: 'sb_hero_centered',
+        name: 'Hero — canh giữa',
+        use: 'Mở đầu trang khi chưa có ảnh: tiêu đề lớn, một câu, một nút',
+        build: (t) => section([h('Tiêu đề chính', 1), p('Một câu nói rõ bạn bán gì và cho ai.'), cta('Mua ngay')], t, { alignItems: 'center', textAlign: 'center' }, { alignItems: 'center' }),
+    },
+    {
+        id: 'sb_feature_trio',
+        name: 'Ba lợi ích',
+        use: 'Ba cột ngang nhau: mỗi cột một tiêu đề nhỏ và một đoạn — lý do nên mua',
+        build: (t) => section([
+            h('Vì sao chọn chúng tôi'),
+            row([
+                { kind: 'group', direction: 'column', children: [h('Lợi ích một', 3), p('Một hoặc hai câu.')] },
+                { kind: 'group', direction: 'column', children: [h('Lợi ích hai', 3), p('Một hoặc hai câu.')] },
+                { kind: 'group', direction: 'column', children: [h('Lợi ích ba', 3), p('Một hoặc hai câu.')] },
+            ]),
+        ], t),
+    },
+    {
+        id: 'sb_stats_row',
+        name: 'Dải số liệu',
+        use: 'Ba đến bốn con số lớn với nhãn bên dưới — bằng chứng, không phải lời hứa',
+        build: (t) => section([
+            row([
+                { kind: 'group', direction: 'column', children: [h('1.000+', 2), p('Khách hàng')] },
+                { kind: 'group', direction: 'column', children: [h('4,9/5', 2), p('Đánh giá trung bình')] },
+                { kind: 'group', direction: 'column', children: [h('24h', 2), p('Giao trong nội thành')] },
+            ]),
+        ], t, { alignItems: 'center', textAlign: 'center' }, { alignItems: 'center' }),
+    },
+    {
+        id: 'sb_cta_band',
+        name: 'Dải kêu gọi hành động',
+        use: 'Một câu và một nút, đặt cuối trang hoặc giữa hai band nội dung',
+        build: (t) => section([h('Sẵn sàng bắt đầu?'), p('Một câu nhắc lại lời hứa chính.'), cta('Mua ngay')], t, { alignItems: 'center', textAlign: 'center' }, { alignItems: 'center' }),
+    },
+    {
+        id: 'sb_faq',
+        name: 'Câu hỏi thường gặp',
+        use: 'Ba câu hỏi mở/đóng — nơi trả lời những gì cản trở việc mua',
+        build: (t) => section([
+            h('Câu hỏi thường gặp'),
+            {
+                kind: 'accordion',
+                children: [
+                    { kind: 'accordion-item', text: 'Giao hàng mất bao lâu?', children: [p('Trả lời ngắn gọn.')] },
+                    { kind: 'accordion-item', text: 'Đổi trả thế nào?', children: [p('Trả lời ngắn gọn.')] },
+                    { kind: 'accordion-item', text: 'Thanh toán ra sao?', children: [p('Trả lời ngắn gọn.')] },
+                ],
+            },
+        ], t),
+    },
+];
+export const PATTERN_BY_ID = new Map(LAYOUT_PATTERNS.map((p2) => [p2.id, p2]));

package/dist/tools/page.js

@@ -20,6 +20,9 @@ import { readinessGaps, READINESS_NOTICE } from '../domains/site/readiness.js';
 import { gatherReadiness } from '../domains/site/readiness-fetch.js';
 import { globalWarning, restampPatches, RESPONSIVE_NOTICE } from '../domains/site/traps.js';
 import { catalogMatches, traitsFor } from '../catalog/element-search.js';
+import { LAYOUT_PATTERNS, PATTERN_BY_ID, THEME_TOKENS } from '../domains/site/patterns.js';
+import { tokensFromPage } from '../domains/site/importmap.js';
+import { middleEnd } from '../domains/site/traps.js';
 import { applyPatches } from '../core/patch.js';
 import { stickyWarning } from '../domains/site/sticky.js';
 import { HOVER_STATE, PARENT_HOVER_STATE, hoverHostNote, hoverRoutingNote } from '../domains/site/hover.js';
@@ -654,16 +657,27 @@ export function registerPageTools(server, ctx) {
             'than assembling one. Use sb_template_use to drop one into the open page.',
         inputSchema: { site_id: z.string().optional() },
         annotations: { readOnlyHint: true },
-    }, async ({ site_id: given }) => text(projectList(await request({
-        base: ctx.base,
-        method: 'GET',
-        path: `/api/sites/${encodeURIComponent(siteFor(ctx, given))}/section-templates`,
-        token: siteToken(ctx),
-        fetchImpl: ctx.fetchImpl,
-    }), 'sectionTemplates', TEMPLATE_FIELDS)));
+    }, async ({ site_id: given }) => {
+        const listed = projectList(await request({
+            base: ctx.base,
+            method: 'GET',
+            path: `/api/sites/${encodeURIComponent(siteFor(ctx, given))}/section-templates`,
+            token: siteToken(ctx),
+            fetchImpl: ctx.fetchImpl,
+        }), 'sectionTemplates', TEMPLATE_FIELDS);
+        // THE SITE'S OWN FIRST, ALWAYS. A template a merchant designed is this
+        // site's answer; these are defaults for a page that has none. Measured on
+        // a live site, the platform's library held TWO — which is why an agent
+        // asked for "a hero" was inventing one from flex-blocks every time.
+        return text({
+            ...listed,
+            built_in: LAYOUT_PATTERNS.map((p) => ({ id: p.id, name: p.name, use: p.use })),
+        });
+    });
     server.registerTool('sb_template_use', {
-        description: 'Instantiate a saved section template into a page. The server does the copy, so the ' +
-            'section arrives exactly as it was designed — then re-open the page to see it.',
+        description: 'Instantiate a section template into a page — the site\'s own (the server copies it) or ' +
+            'one of the BUILT-IN layouts sb_templates lists, which are composed against this ' +
+            "page's own tokens rather than copied.",
         inputSchema: {
             site_id: z.string().optional(),
             template_id: z.string(),
@@ -673,6 +687,54 @@ export function registerPageTools(server, ctx) {
         annotations: { readOnlyHint: false, destructiveHint: false },
     }, async ({ site_id: given, template_id, page_id, dry_run }) => {
         const site_id = siteFor(ctx, given);
+        // A BUILT-IN IS NOT A SERVER COPY. The platform's own templates are
+        // instantiated by the platform, which is why the section arrives exactly
+        // as designed; a built-in has no row on the server, so it is composed HERE
+        // — against the target page's own tokens, which is the whole point of it
+        // being a pattern rather than a snapshot.
+        const pattern = PATTERN_BY_ID.get(template_id);
+        if (pattern) {
+            await session.open(site_id, page_id);
+            const doc = session.current();
+            const read = tokensFromPage(doc.doc);
+            // A BLANK PAGE HAS NO PATTERN TO READ, and the next authority is the
+            // site's THEME rather than nothing — every element's style preset
+            // resolves from it anyway. Carried as `var(--wb-color-…)`, so the band
+            // goes on following the theme instead of freezing today's hex into it.
+            const fromTheme = Object.keys(read).length === 0;
+            const tokens = fromTheme ? THEME_TOKENS : read;
+            const spec = pattern.build(tokens);
+            if (!spec) {
+                throw new Error(`sbuilder: the built-in "${template_id}" produced nothing to add.`);
+            }
+            const { patches, ids } = addSubtree(doc, doc.doc.root_node_id, spec, middleEnd(doc.doc));
+            if (dry_run !== false) {
+                return text({
+                    dry_run: true,
+                    would_add: pattern.name,
+                    nodes: ids.length,
+                    into: page_id,
+                    tokens_from: fromTheme ? "this site's theme — the page has no look of its own yet" : 'this page',
+                    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.',
+                });
+            }
+            await session.applyAndSave(patches);
+            return text({
+                added: pattern.name,
+                section: ids[0],
+                nodes: ids.length,
+                into: page_id,
+                rev: doc.rev,
+                ...(fromTheme
+                    ? {
+                        tokens_from: "this site's theme — the page had no heading, button or section to read a look " +
+                            'off, so the band carries var(--wb-color-…) and follows the theme rather than a ' +
+                            'frozen colour. Style this first band and every pattern after it reads THAT.',
+                    }
+                    : {}),
+            });
+        }
         const path = `/api/sites/${encodeURIComponent(site_id)}/section-templates/${encodeURIComponent(template_id)}/instantiate`;
         if (dry_run !== false) {
             return text({ dry_run: true, would_post: path, body: { pageId: page_id } });

package/dist/transport/media.js

@@ -41,8 +41,87 @@ function typeForName(name) {
     const dot = name.lastIndexOf('.');
     return dot < 0 ? '' : (TYPE_BY_EXT[name.slice(dot).toLowerCase()] ?? '');
 }
+/**
+ * Ask the platform to fetch the URL itself.
+ *
+ * Returns the asset when the server took it, or null when the ROUTE is not
+ * there — an older deployment — which is the one case the caller may answer by
+ * downloading the bytes and posting them the old way.
+ *
+ * A REFUSAL IS TERMINAL, and that is a security rule rather than tidiness. The
+ * server refuses an address that is not on the public internet (`remote_blocked`
+ * — loopback, private ranges, the cloud metadata endpoint), and a client that
+ * answered by fetching that same URL from its OWN machine and uploading the
+ * bytes would walk straight around the guard. The agent's network is not the
+ * server's, but "the caller does it instead" is exactly the bypass the check
+ * exists to prevent, so the error is raised rather than worked around.
+ */
+async function fromUrl(ctx, siteId, url, source) {
+    const doFetch = ctx.fetchImpl ?? fetch;
+    const res = await doFetch(`${ctx.base.replace(/\/$/, '')}/api/media/${encodeURIComponent(siteId)}/from-url`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${siteToken(ctx)}`,
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+            ...identityHeaders(),
+        },
+        body: JSON.stringify({
+            url,
+            ...(source.name ? { name: source.name } : {}),
+            ...(source.folderId ? { folderId: source.folderId } : {}),
+        }),
+    });
+    // 404/405 is "this build has no such route". Anything else is an answer.
+    if (res.status === 404 || res.status === 405)
+        return null;
+    const raw = await res.text();
+    let parsed = {};
+    try {
+        parsed = raw ? JSON.parse(raw) : {};
+    }
+    catch {
+        // A build that routes this path to something else entirely. Fall back rather
+        // than reporting a parse error the caller cannot act on.
+        return null;
+    }
+    if (!res.ok) {
+        const env = (parsed ?? {});
+        if (env.code === 'remote_blocked') {
+            throw new ApiError(res.status, 'remote_blocked', `sbuilder: the platform refuses to fetch ${url} — it is not an address on the public ` +
+                'internet. This server will not fetch it on the platform\'s behalf either: that would ' +
+                'walk around the check rather than satisfy it. Give a public URL, or upload the file ' +
+                'with a local path.');
+        }
+        if (env.code === 'remote_unreachable') {
+            // THE PLATFORM'S OWN REASON, not a sentence of ours over the top of it. It
+            // says which host answered what — a 404 is a wrong URL, a 403 is an origin
+            // refusing this fetcher, a timeout is worth retrying — and replacing that
+            // with "could not read it" sends all of them to check their network.
+            throw new ApiError(res.status, 'remote_unreachable', `sbuilder: the platform could not fetch ${url} — ${env.error ?? 'no reason given'}.`);
+        }
+        // Any OTHER refusal — 401, 403, 413, an unsupported type — is one the older
+        // path answers with its own, better-worded diagnosis. Let it try.
+        return null;
+    }
+    const body = (parsed ?? {});
+    return body.asset ?? parsed;
+}
 export async function uploadMedia(ctx, siteId, source) {
     const doFetch = ctx.fetchImpl ?? fetch;
+    // THE SERVER'S OWN DOOR FIRST, when the source is a URL.
+    //
+    // `POST /api/media/{siteId}/from-url` fetches it where the platform already
+    // guards outbound requests, so the bytes make ONE hop instead of two and the
+    // content type is decided by the origin's own answer rather than reconstructed
+    // here. Everything below this is the older path, kept because a deployment
+    // without that route must still be able to upload — the same shape the partner
+    // -surface retry below has, and for the same reason.
+    if (source.url) {
+        const viaServer = await fromUrl(ctx, siteId, source.url, source);
+        if (viaServer)
+            return viaServer;
+    }
     let bytes;
     let filename;
     let declared = '';

package/package.json

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