sbuilder-mcp 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -6,6 +6,19 @@ 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.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
+- sb_set now refuses a `config.stuckAfter` write the renderer would drop on the floor — a negative, non-finite, or empty value, or one set on a node that cannot pin — instead of silently storing, saving, and publishing a threshold the runtime island never reads and quietly falling back to its automatic answer.
+
 ## [0.9.0] - 2026-09-08
 
 ### Added

package/CHANGELOG.vi.md

@@ -6,6 +6,19 @@ 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.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
+- sb_set giờ từ chối ghi `config.stuckAfter` nếu giá trị sẽ bị renderer âm thầm bỏ qua — số âm, không hữu hạn, rỗng, hoặc được đặt trên một node không thể ghim — thay vì lưu, save rồi publish một ngưỡng mà runtime island không bao giờ đọc và lặng lẽ quay về đáp án tự động của nó.
+
 ## [0.9.0] - 2026-09-08
 
 ### Added

package/dist/domains/site/builder.js

@@ -2,7 +2,7 @@ import { isOverlay, subtreeIds, ancestors, appBlockRoot, SPEC_GLOBAL_ID, SPEC_GL
 import { ELEMENTS, ELEMENT_SEEDS, SATELLITE_RULES } from '../../catalog/elements.generated.js';
 import { bindingsForConfig, createNode, mintSatellites } from './node.js';
 import { refuseSecondTemplate } from './traps.js';
-import { STUCK_STATE, refuseStuckConfig, requireStuckHost, stickySeeds } from './sticky.js';
+import { STUCK_STATE, refuseStuckAfter, refuseStuckConfig, requireStuckHost, stickySeeds, } from './sticky.js';
 import { genId } from './ids.js';
 /** Append sentinel: splice clamps a too-large index, and `isSyncablePatch`
  *  deliberately allows one — an append is a legitimate thing to describe. */
@@ -182,6 +182,12 @@ export function setKeys(doc, id, keys, opts) {
     // the same silent shape as an unbound element, which cost a whole page of
     // "$0.00" cards to find once.
     const rebind = namespace === 'config' ? rebindPatch(doc, id, keys) : null;
+    // The scroll THRESHOLD is a plain config key, and the renderer drops it in two
+    // different ways without a word — see sticky.ts. Checked here rather than in
+    // the state branch because it is written on the node that PINS, at base or at
+    // a breakpoint, never inside a stuck slot.
+    if (namespace === 'config')
+        refuseStuckAfter(doc.doc, id, keys);
     if (namespace === 'specials') {
         refuseComposedStamp(keys);
         // `specials` is content and identity, base-only by definition, and states

package/dist/domains/site/sticky.js

@@ -36,6 +36,17 @@ import { ancestors } from '../../core/tree.js';
  */
 /** The state key, in `node.states` and `responsive[bp].states`. */
 export const STUCK_STATE = 'stuck';
+/**
+ * The config key holding "pinned from WHEN?", in px of page scroll.
+ *
+ * It reaches the runtime island as a CSS custom property (`--wb-stuck-after`)
+ * rather than through `wb:props`, because it is per breakpoint and the cascade
+ * is what picks the right number at the right width. Unset is the common case:
+ * the island then decides from the element itself — a sticky one the moment it
+ * is held away from its place in the flow, a fixed one the moment the page
+ * scrolls past where it would have sat.
+ */
+export const STUCK_AFTER = 'stuckAfter';
 /**
  * The positions that HAVE a pinned moment.
  *
@@ -206,3 +217,32 @@ export function stickyWarning(doc, id, bp) {
         `scrolls. The node will not move. Clear overflowX/overflowY on ${blocker}, or pin a node ` +
         'outside it.');
 }
+/**
+ * Refuse a `stuckAfter` that the renderer would drop on the floor.
+ *
+ * `stuckAfterCss` emits the custom property only for a node that CAN pin and
+ * that carries a usable number, and returns an empty string otherwise — so both
+ * mistakes here are stored, saved, published and read by nothing. The value
+ * rules are the platform's own: zero is honoured ("as soon as the page moves at
+ * all" is a real answer, and dropping it would silently fall back to the
+ * automatic one); negative and non-finite are not, because no scroll position
+ * can satisfy them.
+ */
+export function refuseStuckAfter(doc, id, keys) {
+    if (!(STUCK_AFTER in keys))
+        return;
+    const raw = keys[STUCK_AFTER];
+    const n = typeof raw === 'number' ? raw : Number(raw);
+    if (raw == null || raw === '' || !Number.isFinite(n) || n < 0) {
+        throw new Error(`sbuilder: config.${STUCK_AFTER} is px of page scroll — a finite number, zero or more ` +
+            `(0 means "as soon as the page moves at all"). ${JSON.stringify(raw)} is dropped by ` +
+            "the renderer, which then falls back to the island's automatic answer without saying " +
+            'so. To go back to automatic, remove the key.');
+    }
+    if (!isPinnedNode(doc.nodes[id])) {
+        throw new Error(`sbuilder: config.${STUCK_AFTER} says WHEN a pinned element counts as stuck, and ${id} ` +
+            'cannot pin — the renderer emits the threshold only for a node that can ' +
+            '(stickyState.ts stuckAfterCss), so this would be stored and read by nothing. ' +
+            `Pin it first: sb_set ${id} style { position: "sticky" }.`);
+    }
+}

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

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