sbuilder-mcp 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -6,6 +6,22 @@ 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.10.0] - 2026-09-09
+
+### Added
+- sb_set now takes `unset`, an array of key names removed from the same slot a write would target — base, a breakpoint, or either home of a state — giving every finding that names "remove the override" as its fix a tool that can actually perform it. `keys` is now optional when `unset` carries the work, and a pure removal is exempt from the sticky-host guard so it can repair a `stuck_no_host` finding rather than being refused by it.
+
+### Fixed
+- sb_review's `stuck_no_host` check now counts the keys inside a stuck state slot instead of only checking whether the slot exists, matching the platform's own `HasStuckOverrides`; an empty slot (the state a repair with `unset` leaves behind) no longer keeps reporting the finding it was used to fix.
+
+## [0.9.2] - 2026-09-09
+
+### Added
+- sb_look now reports `stuck_note` once per process when the page pins something (`position: sticky` or `fixed`), explaining that a screenshot cannot show whether the element is actually stuck and pointing at a browser server (Playwright MCP or Chrome DevTools MCP) to scroll and check for the `wb-stuck` class.
+
+### Internal
+- docs/tools.md and the sbuilder-site-design skill now document which of the other MCP servers (Figma, Google Stitch, Chrome DevTools, Playwright) answers which question, alongside sb_look, covering six cases a screenshot alone cannot settle: a sticky header actually engaging, a style that "did not apply", a cart drawer's click trigger, a checkout submission, an entity template previewed with a real record, and layout stability (CLS).
+
 ## [0.9.1] - 2026-09-09
 
 ### Fixed

package/CHANGELOG.vi.md

@@ -6,6 +6,22 @@ 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.10.0] - 2026-09-09
+
+### Added
+- sb_set giờ nhận `unset`, một mảng tên key cần xoá khỏi đúng slot mà một lần ghi sẽ nhắm tới — base, một breakpoint, hoặc một trong hai nơi lưu của một state — nhờ đó mọi finding nêu "xoá override đi" làm cách sửa giờ có công cụ để thực sự làm điều đó. `keys` giờ có thể bỏ qua khi `unset` đã làm phần việc, và một lần xoá thuần tuý được miễn khỏi kiểm tra sticky-host để nó có thể sửa một finding `stuck_no_host` thay vì bị chính kiểm tra đó từ chối.
+
+### Fixed
+- Kiểm tra `stuck_no_host` của sb_review giờ đếm số key bên trong slot trạng thái stuck thay vì chỉ kiểm tra slot có tồn tại hay không, khớp với `HasStuckOverrides` của chính nền tảng; một slot rỗng (trạng thái mà một lần sửa bằng `unset` để lại) không còn tiếp tục báo cáo finding mà nó vừa được dùng để khắc phục.
+
+## [0.9.2] - 2026-09-09
+
+### Added
+- sb_look giờ báo cáo `stuck_note` một lần mỗi tiến trình khi trang có ghim một phần tử (`position: sticky` hoặc `fixed`), giải thích rằng một ảnh chụp màn hình không thể cho biết phần tử đó có thực sự bị "stuck" hay không, và chỉ ra một trình duyệt server (Playwright MCP hoặc Chrome DevTools MCP) để cuộn trang và kiểm tra class `wb-stuck`.
+
+### Internal
+- docs/tools.md và skill sbuilder-site-design giờ ghi lại server MCP nào (Figma, Google Stitch, Chrome DevTools, Playwright) trả lời câu hỏi nào, bên cạnh sb_look, bao quát sáu trường hợp mà chỉ riêng ảnh chụp màn hình không thể trả lời: một header sticky có thực sự ghim hay không, một style "không được áp dụng", nút bấm mở giỏ hàng, việc submit checkout, xem trước một template entity với dữ liệu thật, và độ ổn định bố cục (CLS).
+
 ## [0.9.1] - 2026-09-09
 
 ### Fixed

package/dist/domains/site/builder.js

@@ -188,6 +188,21 @@ export function setKeys(doc, id, keys, opts) {
     // a breakpoint, never inside a stuck slot.
     if (namespace === 'config')
         refuseStuckAfter(doc.doc, id, keys);
+    // The paths `keys` and `unset` share. Computed once so a removal can never
+    // land somewhere a write would not have.
+    const slot = () => {
+        if (namespace === 'specials')
+            return ['nodes', id, 'specials'];
+        if (opts.state) {
+            return opts.base
+                ? ['nodes', id, 'states', opts.state, namespace]
+                : ['nodes', id, 'responsive', opts.breakpoint ?? 'desktop', 'states', opts.state, namespace];
+        }
+        if (opts.base)
+            return ['nodes', id, namespace];
+        return ['nodes', id, 'responsive', opts.breakpoint ?? 'desktop', namespace];
+    };
+    const removals = (opts.unset ?? []).map((k) => ({ op: 'unset', path: [...slot(), k] }));
     if (namespace === 'specials') {
         refuseComposedStamp(keys);
         // `specials` is content and identity, base-only by definition, and states
@@ -198,11 +213,14 @@ export function setKeys(doc, id, keys, opts) {
                 'specials is content and identity (text, htmlTag, bound…), which do not vary by ' +
                 'state. Style is what has states.');
         }
-        return Object.entries(keys).map(([k, v]) => ({
-            op: 'set',
-            path: ['nodes', id, 'specials', k],
-            value: v,
-        }));
+        return [
+            ...Object.entries(keys).map(([k, v]) => ({
+                op: 'set',
+                path: ['nodes', id, 'specials', k],
+                value: v,
+            })),
+            ...removals,
+        ];
     }
     // A STATE IS ANSWERED BEFORE `base`, because `base` used to be tested first
     // and swallowed it: `base:true state:"hover"` wrote the hover value straight
@@ -216,7 +234,10 @@ export function setKeys(doc, id, keys, opts) {
         // class a runtime island toggles on the PINNED element, and the renderer
         // emits no rule at all when there is nothing pinned to hang it off. See
         // sticky.ts — this is the whole reason that module exists.
-        if (opts.state === STUCK_STATE) {
+        // A pure REMOVAL is exempt: unsetting a hostless stuck override is exactly
+        // the repair `sb_review` asks for, and refusing it would leave the caller
+        // holding a finding they cannot act on.
+        if (opts.state === STUCK_STATE && Object.keys(keys).length) {
             requireStuckHost(doc.doc, id);
             if (namespace === 'config')
                 refuseStuckConfig(keys);
@@ -233,6 +254,7 @@ export function setKeys(doc, id, keys, opts) {
                 path: [...prefix, namespace, k],
                 value: v,
             })),
+            ...removals,
             ...(rebind ? [rebind] : []),
         ];
     }
@@ -270,6 +292,7 @@ export function setKeys(doc, id, keys, opts) {
                 path: ['nodes', id, namespace, k],
                 value: v,
             })),
+            ...removals,
             ...(rebind ? [rebind] : []),
         ];
     }
@@ -280,6 +303,7 @@ export function setKeys(doc, id, keys, opts) {
             path: ['nodes', id, 'responsive', bp, namespace, k],
             value: v,
         })),
+        ...removals,
         ...(rebind ? [rebind] : []),
     ];
 }
@@ -492,7 +516,7 @@ export function setMany(doc, edits) {
     const patches = [];
     const touched = [];
     for (const e of edits) {
-        patches.push(...setKeys(doc, e.id, e.keys, { namespace: e.namespace, breakpoint: e.breakpoint, base: e.base, state: e.state }));
+        patches.push(...setKeys(doc, e.id, e.keys, { namespace: e.namespace, breakpoint: e.breakpoint, base: e.base, state: e.state, unset: e.unset }));
         touched.push({ id: e.id, keys: Object.keys(e.keys) });
     }
     return { patches, touched };

package/dist/domains/site/review.js

@@ -214,8 +214,20 @@ export function reviewDesign(doc) {
                 });
             }
         }
-        const hasStuck = styled.states?.[STUCK_STATE] !== undefined ||
-            Object.values(styled.responsive ?? {}).some((r) => r?.states?.[STUCK_STATE] !== undefined);
+        // COUNT THE KEYS, don't ask whether the slot exists — the platform's own
+        // `HasStuckOverrides` tests `len(slot.Style) > 0`, and an EMPTY slot paints
+        // nothing whether or not there is a host. Asking the weaker question made
+        // this a false positive on the one document the fix produces: unsetting the
+        // last key leaves `{}` behind, so the repair the finding names left the
+        // finding standing.
+        const stuckSlots = [
+            styled.states?.[STUCK_STATE],
+            ...Object.values(styled.responsive ?? {}).map((r) => r?.states?.[STUCK_STATE]),
+        ];
+        const hasStuck = stuckSlots.some((slot) => {
+            const s = slot;
+            return !!s && (Object.keys(s.style ?? {}).length > 0 || Object.keys(s.config ?? {}).length > 0);
+        });
         if (hasStuck && !stuckHostOf(d, id)) {
             out.push({
                 code: 'stuck_no_host',

package/dist/tools/live.js

@@ -7,6 +7,7 @@ import { uploadMedia } from '../transport/media.js';
 import { request } from '../transport/http.js';
 import { shoot, DEFAULT_WIDTHS } from '../vision/shoot.js';
 import { measure, MEASURE_NOTICE } from '../vision/measure.js';
+import { isPinnedNode } from '../domains/site/sticky.js';
 import { compactFindings } from '../domains/site/findings.js';
 import { reviewField } from './page.js';
 import { boxesForResponse, BOXES_FORMAT } from '../vision/boxes.js';
@@ -340,10 +341,30 @@ export function registerLiveTools(server, ctx, session) {
                 '("Color / Size", "Red / S") rather than the product\'s own. That is the preview, ' +
                 'not the page. Pass a published storefront URL as `url` to judge a template.')
             : undefined;
+        // A STILL PICTURE CANNOT SHOW A PINNED ELEMENT ENGAGING, and this is the
+        // one tool a caller would expect to. `position: sticky` looks identical at
+        // rest and while stuck — that is the whole reason the platform needs a
+        // runtime class for it — so a page carrying a pinned node has a look this
+        // tool is structurally unable to photograph, however many widths it shoots.
+        //
+        // Gated on the document actually carrying one, and said once, for the same
+        // reason `preview_note` is: a directive that fires on pages it cannot
+        // apply to is noise, and noise is what makes the real notes unread.
+        const pinned = Object.values(session.current().doc.nodes).some((n) => isPinnedNode(n));
+        const stuckNote = pinned
+            ? ctx.notices.once('stuck-scroll', 'This page pins something (position sticky/fixed). A screenshot is ONE scroll ' +
+                'position, so nothing here can show whether it engages or what it looks like ' +
+                'once it does — the platform styles that moment through a class a runtime island ' +
+                'toggles, "wb-stuck", and CSS alone cannot express it. To check: open the ' +
+                'PUBLISHED page in a browser server (Playwright or Chrome DevTools MCP), scroll, ' +
+                'and read classList for "wb-stuck". If it never appears, every stuck override on ' +
+                'the page is stored and never painted.')
+            : undefined;
         return images(shots.map((s) => ({ dataBase64: s.imageBase64, mimeType: s.mimeType })), {
             widths: shots.map((s) => s.width),
             ...(url ? { shot: url } : {}),
             ...(previewNote ? { preview_note: previewNote } : {}),
+            ...(stuckNote ? { stuck_note: stuckNote } : {}),
             ...(node_id ? { framed: node_id } : {}),
             ...(with_boxes === false
                 ? {}

package/dist/tools/page.js

@@ -262,6 +262,11 @@ export function registerPageTools(server, ctx) {
             id: z.string().optional(),
             namespace: z.enum(['style', 'config', 'specials']).optional(),
             keys: z.record(z.unknown()).optional(),
+            unset: z
+                .array(z.string())
+                .optional()
+                .describe('Keys to REMOVE from the same slot — the only way to undo a write. Setting null ' +
+                'is not the same: null is a stored value, so the override still counts as present.'),
             breakpoint: z.enum(['desktop', 'laptop', 'tablet', 'mobile']).optional(),
             base: z.boolean().optional(),
             state: z
@@ -278,20 +283,24 @@ export function registerPageTools(server, ctx) {
                 breakpoint: z.enum(['desktop', 'laptop', 'tablet', 'mobile']).optional(),
                 base: z.boolean().optional(),
                 state: z.string().optional(),
+                unset: z.array(z.string()).optional(),
             }))
                 .optional(),
             dry_run: z.boolean().optional(),
         },
         annotations: { readOnlyHint: false, destructiveHint: false },
-    }, async ({ id, namespace, keys, breakpoint, base, state, edits, dry_run }) => {
+    }, async ({ id, namespace, keys, breakpoint, base, state, unset, edits, dry_run }) => {
         const d = session.current();
         // One shape inside: a single edit is a batch of one.
         const batch = edits ?? [];
         if (!edits) {
-            if (!id || !namespace || !keys) {
-                throw new Error('sbuilder: sb_set needs id + namespace + keys, or edits[]');
+            // `keys` is optional when `unset` carries the work: a pure removal is a
+            // legitimate edit, and demanding an empty object alongside it would make
+            // the repair `sb_review` names read like a workaround.
+            if (!id || !namespace || (!keys && !unset?.length)) {
+                throw new Error('sbuilder: sb_set needs id + namespace + keys (or unset), or edits[]');
             }
-            batch.push({ id, namespace, keys, breakpoint: breakpoint, base, state });
+            batch.push({ id, namespace, keys: keys ?? {}, breakpoint: breakpoint, base, state, unset });
         }
         const { patches, touched } = setMany(d, batch);
         // THE STICKY WARNING IS COMPUTED AGAINST THE DOCUMENT AS IT WILL BE, so

package/package.json

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