sbuilder-mcp 0.9.2 → 0.11.0

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.11.0] - 2026-09-09
+
+### Added
+- sb_set's `state:"hover"` now routes each write to the home its element's own renderer actually reads, since the platform's universal hover compiler deliberately stands aside for twelve element types that declare their own Hover variant; a `button` write now lands in `config.stateHover` (flat, base-only) instead of the unread `states.hover` slot, and the response reports where it went so a caller reading the node back is not surprised.
+- sb_set refuses a `state:"parentHover"` write on a node with no box to key off — a satellite, a direct child of the page root, or an orphan — naming the reason instead of storing a rule the platform would never match.
+- sb_set refuses `config.revealOnHover` on a node with no such box for the same reason, since the platform emits neither half of the reveal without one and the element would simply stay visible.
+- sb_set now translates `hidden: true` under a hover state into `display: none`, and refuses any other config key or a `false` value, matching the same contract already enforced for the `stuck` state.
+- sb_set warns when a write targets `product-image-list`'s hover state: its meta promises `states.hover`, but measured on 2026-09-09 nothing in the platform compiles it yet, so the override is stored where it belongs and will start painting once the platform closes the gap.
+
+## [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

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.11.0] - 2026-09-09
+
+### Added
+- `state:"hover"` của sb_set giờ định tuyến mỗi lần ghi tới đúng nơi mà renderer của element đó thực sự đọc, vì bộ biên dịch hover phổ quát của nền tảng chủ động đứng ngoài đối với mười hai loại element tự khai báo biến thể Hover riêng; một lần ghi trên `button` giờ vào `config.stateHover` (dạng phẳng, chỉ ở base) thay vì slot `states.hover` không ai đọc, và kết quả trả về cho biết giá trị đã đi vào đâu để người gọi đọc lại node không bị bất ngờ.
+- sb_set từ chối ghi `state:"parentHover"` trên một node không có "hộp" nào để dựa vào — một satellite, một con trực tiếp của root trang, hoặc một node mồ côi — nêu rõ lý do thay vì lưu một rule mà nền tảng sẽ không bao giờ khớp.
+- sb_set từ chối `config.revealOnHover` trên một node không có hộp như vậy vì cùng lý do, vì nền tảng sẽ không phát ra cả hai nửa của hiệu ứng reveal nếu thiếu nó, khiến phần tử đơn giản là luôn hiển thị.
+- sb_set giờ dịch `hidden: true` dưới một hover state thành `display: none`, và từ chối mọi config key khác hoặc giá trị `false`, khớp với đúng quy tắc đã áp dụng cho trạng thái `stuck`.
+- sb_set cảnh báo khi một lần ghi nhắm vào hover state của `product-image-list`: meta của nó hứa hẹn `states.hover`, nhưng đo được vào ngày 2026-09-09 thì chưa có gì trong nền tảng biên dịch nó cả, nên override vẫn được lưu đúng chỗ meta quy định và sẽ bắt đầu hiển thị khi nền tảng khắc phục xong khoảng trống này.
+
+## [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

package/dist/catalog/elements.generated.js

@@ -1,5 +1,5 @@
 export const ELEMENT_SOURCE = {
-    "count": 108,
+    "count": 109,
     "docSchemaVersion": 2
 };
 export const ELEMENTS = {
@@ -1803,7 +1803,8 @@ export const ELEMENTS = {
                         "key": "action",
                         "label": "Action",
                         "controls": [
-                            "action"
+                            "action",
+                            "icon_cart_badge"
                         ]
                     },
                     {
@@ -1876,6 +1877,7 @@ export const ELEMENTS = {
             "icon_color",
             "icon_size",
             "action",
+            "icon_cart_badge",
             "padding",
             "margin",
             "align_self",
@@ -13842,6 +13844,166 @@ export const ELEMENTS = {
             "dynamic"
         ]
     },
+    "cart-count": {
+        "type": "cart-count",
+        "label": "Cart count",
+        "category": "store",
+        "isContainer": false,
+        "isRootOnly": false,
+        "locked": false,
+        "hideInLayer": false,
+        "childAllows": [],
+        "defaults": {
+            "style": {
+                "display": "inline-flex",
+                "alignItems": "center",
+                "justifyContent": "center",
+                "width": "fit-content",
+                "minWidth": "20px",
+                "height": "20px",
+                "paddingLeft": "6px",
+                "paddingRight": "6px",
+                "borderRadius": "999px",
+                "backgroundColor": "#171717",
+                "color": "#ffffff",
+                "fontSize": "12px",
+                "fontWeight": "600",
+                "lineHeight": "1"
+            },
+            "specials": {
+                "placeholder": "0",
+                "hideWhenEmpty": true
+            }
+        },
+        "inspector": [
+            {
+                "tab": "general",
+                "groups": [
+                    {
+                        "key": "content",
+                        "label": "Content",
+                        "controls": [
+                            "cart_count_placeholder",
+                            "cart_count_hide_empty"
+                        ]
+                    },
+                    {
+                        "key": "size",
+                        "label": "Size",
+                        "controls": [
+                            "width_select",
+                            "height_select",
+                            "size_bounds"
+                        ]
+                    },
+                    {
+                        "key": "layout",
+                        "label": "Layout",
+                        "controls": [
+                            "padding",
+                            "margin",
+                            "vertical",
+                            "horizontal"
+                        ]
+                    },
+                    {
+                        "key": "typography",
+                        "label": "Typography",
+                        "controls": [
+                            "font_family",
+                            "font_size",
+                            "text_style",
+                            "text_color"
+                        ]
+                    },
+                    {
+                        "key": "background",
+                        "label": "Background",
+                        "controls": [
+                            "bg_color"
+                        ]
+                    },
+                    {
+                        "key": "shape",
+                        "label": "Shape",
+                        "controls": [
+                            "border",
+                            "corner"
+                        ]
+                    }
+                ]
+            },
+            {
+                "tab": "advanced",
+                "groups": [
+                    {
+                        "key": "spacing",
+                        "label": "Spacing",
+                        "controls": [
+                            "padding_margin"
+                        ]
+                    },
+                    {
+                        "key": "display",
+                        "label": "Display",
+                        "controls": [
+                            "display"
+                        ]
+                    },
+                    {
+                        "key": "class_css",
+                        "label": "Class",
+                        "controls": [
+                            "class_css"
+                        ]
+                    }
+                ]
+            }
+        ],
+        "controls": [
+            "cart_count_placeholder",
+            "cart_count_hide_empty",
+            "width_select",
+            "height_select",
+            "size_bounds",
+            "padding",
+            "margin",
+            "vertical",
+            "horizontal",
+            "font_family",
+            "font_size",
+            "text_style",
+            "text_color",
+            "bg_color",
+            "border",
+            "corner",
+            "padding_margin",
+            "display",
+            "class_css"
+        ],
+        "description": "The number of items in the shopper's cart, as a small badge. The figure comes from the shopper's own cart in their browser, so it changes the moment they add, remove or re-count a line. Its usual home is the cart icon in the site header, where it is the only evidence on the page that the basket holds anything.",
+        "useWhen": [
+            "a header or navigation bar carries a cart icon and a shopper needs to see the basket is not empty",
+            "building a sticky mobile bar or a mini-cart trigger anywhere outside the cart drawer"
+        ],
+        "avoidWhen": [
+            "showing what the cart COSTS — that is a cart-total, which reads a money figure",
+            "showing how many of ONE product a shopper picked — that is the quantity stepper on the product",
+            "showing a past order’s item count; an order is a record, not the live cart"
+        ],
+        "contentTips": [
+            "the placeholder is what the badge reads before the shopper’s cart is known, so write it as a real empty-cart count",
+            "leave “hide when empty” on unless the header’s layout must never shift when the first item lands",
+            "to put it on a cart icon, turn the badge on from the icon’s own inspector rather than placing this element and positioning it by hand"
+        ],
+        "semantics": [
+            "cart",
+            "count",
+            "badge",
+            "header",
+            "commerce"
+        ]
+    },
     "cart-total": {
         "type": "cart-total",
         "label": "Cart total",
@@ -33564,6 +33726,11 @@ export const TRAIT_WRITES = {
                 "target": "config",
                 "writeKey": "hidden",
                 "type": "boolean"
+            },
+            {
+                "target": "config",
+                "writeKey": "revealOnHover",
+                "type": "boolean"
             }
         ]
     },
@@ -33672,6 +33839,28 @@ export const TRAIT_WRITES = {
             }
         ]
     },
+    "cart_count_placeholder": {
+        "key": "cart_count_placeholder",
+        "label": "Empty count",
+        "writes": [
+            {
+                "target": "specials",
+                "writeKey": "placeholder",
+                "type": "string"
+            }
+        ]
+    },
+    "cart_count_hide_empty": {
+        "key": "cart_count_hide_empty",
+        "label": "Hide when empty",
+        "writes": [
+            {
+                "target": "specials",
+                "writeKey": "hideWhenEmpty",
+                "type": "boolean"
+            }
+        ]
+    },
     "cart_total_placeholder": {
         "key": "cart_total_placeholder",
         "label": "Empty amount",
@@ -34032,6 +34221,13 @@ export const TRAIT_WRITES = {
     }
 };
 export const SATELLITE_RULES = {
+    "icon": [
+        {
+            "type": "cart-count",
+            "configKey": "cartCountId",
+            "optional": true
+        }
+    ],
     "tab": [
         {
             "type": "tab-item",
@@ -34600,3 +34796,41 @@ export const ELEMENT_SEEDS = {
 export const FIRST_CHILD_ONLY = [
     "list-dataset"
 ];
+export const HOVER_HOMES = {
+    "button": {
+        "home": "legacy"
+    },
+    "filter-checkbox": {
+        "home": "state"
+    },
+    "filter-color": {
+        "home": "state"
+    },
+    "filter-radio": {
+        "home": "state"
+    },
+    "filter-tag": {
+        "home": "state"
+    },
+    "tab-item": {
+        "home": "state"
+    },
+    "accordion-item": {
+        "home": "state"
+    },
+    "menu-item": {
+        "home": "state"
+    },
+    "product-image-list": {
+        "home": "state"
+    },
+    "quantity-button": {
+        "home": "state"
+    },
+    "product-variant-option": {
+        "home": "state"
+    },
+    "text-dataset": {
+        "home": "state"
+    }
+};

package/dist/domains/site/builder.js

@@ -3,6 +3,7 @@ import { ELEMENTS, ELEMENT_SEEDS, SATELLITE_RULES } from '../../catalog/elements
 import { bindingsForConfig, createNode, mintSatellites } from './node.js';
 import { refuseSecondTemplate } from './traps.js';
 import { STUCK_STATE, refuseStuckAfter, refuseStuckConfig, requireStuckHost, stickySeeds, } from './sticky.js';
+import { HOVER_STATE, PARENT_HOVER_STATE, hoverHome, legacyHoverPath, refuseHoverConfig, refuseReveal, requireHoverHost, } from './hover.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. */
@@ -186,8 +187,27 @@ export function setKeys(doc, id, keys, opts) {
     // 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')
+    if (namespace === 'config') {
         refuseStuckAfter(doc.doc, id, keys);
+        // The reveal is a BASE-level config key with a host precondition, so it is
+        // checked here rather than in the state branch — it is not a state at all.
+        refuseReveal(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 +218,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,11 +239,40 @@ 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);
         }
+        // THE PARENT-HOVER STATE has a host precondition of its own, and a different
+        // one: not "something pins above me" but "I am a real child of a real box".
+        if (opts.state === PARENT_HOVER_STATE && Object.keys(keys).length) {
+            requireHoverHost(doc.doc, id);
+        }
+        if ((opts.state === HOVER_STATE || opts.state === PARENT_HOVER_STATE) &&
+            namespace === 'config' &&
+            Object.keys(keys).length) {
+            refuseHoverConfig(keys, opts.state);
+        }
+        // HOVER HAS THREE HOMES and only one of them is `states.hover`. An element
+        // that declares a Hover variant of its own is served by its own renderer
+        // from a flat, base-only `config.stateHover` map, and the universal compiler
+        // stands aside for it — so writing the state slot here would store keys no
+        // compiler reads. Routed rather than refused: the caller asked for a hover
+        // and there is a home that works; `hoverRoutingNote` says where it went.
+        if (opts.state === HOVER_STATE && namespace === 'style' && hoverHome(doc.node(id).data.type) === 'legacy') {
+            return [
+                ...Object.entries(keys).map(([k, v]) => ({
+                    op: 'set',
+                    path: legacyHoverPath(id, k),
+                    value: v,
+                })),
+                ...(opts.unset ?? []).map((k) => ({ op: 'unset', path: legacyHoverPath(id, k) })),
+            ];
+        }
         // Base state and per-breakpoint state are DIFFERENT PLACES in the document,
         // and the old path (`states[state][bp][ns]`) was neither of them: it buried
         // a breakpoint inside the base-state cluster, where nothing reads it.
@@ -233,6 +285,7 @@ export function setKeys(doc, id, keys, opts) {
                 path: [...prefix, namespace, k],
                 value: v,
             })),
+            ...removals,
             ...(rebind ? [rebind] : []),
         ];
     }
@@ -270,6 +323,7 @@ export function setKeys(doc, id, keys, opts) {
                 path: ['nodes', id, namespace, k],
                 value: v,
             })),
+            ...removals,
             ...(rebind ? [rebind] : []),
         ];
     }
@@ -280,6 +334,7 @@ export function setKeys(doc, id, keys, opts) {
             path: ['nodes', id, 'responsive', bp, namespace, k],
             value: v,
         })),
+        ...removals,
         ...(rebind ? [rebind] : []),
     ];
 }
@@ -492,7 +547,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/hover.js

@@ -0,0 +1,194 @@
+import { HOVER_HOMES } from '../../catalog/elements.generated.js';
+/**
+ * HOVER, AND THE FACT THAT IT HAS THREE HOMES.
+ *
+ * The platform grew a UNIVERSAL hover state in September 2026
+ * (`schema/src/hoverState.ts`, Go mirror `render/style/hover.go`) alongside the
+ * pinned one, and the obvious reading — "hover is `states.hover` now" — is
+ * wrong for twelve element types, silently.
+ *
+ *   states.hover        →  <scope>:hover{…}            the pointer is on THIS
+ *   states.parentHover  →  <host>:hover <scope>{…}     …on the box around this
+ *
+ * But the universal compiler STANDS ASIDE for every element whose meta declares
+ * a Hover variant of its own (`generated.HoverStateOwners`), because those have
+ * their own storage and their own compiler and a second generic rule would fight
+ * the narrower one. For a BUTTON that storage is `config.stateHover` — a flat,
+ * base-only style map — and the editor routes a hover edit there deliberately:
+ * "a hover edit on a button must go on being the button's :hover rule"
+ * (editor/src/trait/values.ts). Nothing reads `states.hover` on a button.
+ *
+ * MEASURED, on one publish of one page: `state:"hover"` on a product card's
+ * dataset-block emitted `@media (hover:hover){#card:hover{…}}`; the identical
+ * write on the BUTTON inside it emitted nothing at all. Both reported success.
+ * Every hover this server had ever written onto a button was dead.
+ *
+ * So the home is a per-type question, and `HOVER_HOMES` is generated from the
+ * metas plus the Go renderers that actually read the legacy map — never
+ * hand-kept, because the platform is still moving here.
+ */
+/** The node's own pointer state. */
+export const HOVER_STATE = 'hover';
+/** "While the box around me is hovered." Universal on every element. */
+export const PARENT_HOVER_STATE = 'parentHover';
+/** The flat, base-only style map a Hover-variant element's own renderer reads. */
+export const LEGACY_HOVER_KEY = 'stateHover';
+/**
+ * The config key behind "only show while the card is hovered". Base-level,
+ * because a state can only override what the base already paints — and, like
+ * the parent state, it needs a host to hover.
+ */
+export const REVEAL_ON_HOVER = 'revealOnHover';
+/**
+ * Where this element type's `hover` state has to be written.
+ *
+ * 'state' is the default and the majority: the universal compiler serves it.
+ */
+/**
+ * Where this element type's `hover` state has to be written.
+ *
+ * 'state' is the default and the overwhelming majority — `node.states.hover`,
+ * compiled either by the universal state or, for the twelve types that declare a
+ * Hover variant, by the element's own CSS. 'legacy' is the flat, base-only
+ * `config.stateHover` map, which is what the element's meta means when it
+ * declares a Hover variant with no `storage: 'node'`.
+ */
+export function hoverHome(type) {
+    return HOVER_HOMES[type]?.home ?? 'state';
+}
+/**
+ * Element types that PROMISE `states.hover` and whose hover nothing compiles.
+ *
+ * Measured 2026-09-09 by rendering one node per Hover-variant type with a
+ * `states.hover` override and looking for the value in `BundleCSS`: every other
+ * type painted, `product-image-list` did not. Its meta declares
+ * `storage: 'node'`, so the value goes where the meta says — and the universal
+ * compiler stands aside for it, while nothing element-specific picks it up.
+ *
+ * A LIST, not a derivation, because there is nothing in the metas to derive it
+ * from: the fact lives in which Go renderer happens to read the slot. It is
+ * therefore a measurement with a date on it, and the note says so rather than
+ * pretending the platform still behaves this way.
+ */
+const HOVER_UNCOMPILED = new Set(['product-image-list']);
+/**
+ * The box whose `:hover` a parent-hover rule keys off, or null.
+ *
+ * Mirrors `HoverHostOf`: the node's PARENT, and only when the node is a real
+ * child of it. Three cases answer null, and each is a rule that would compile to
+ * nothing:
+ *
+ *   - a SATELLITE, which hangs off `config[key]` rather than `data.nodes` and
+ *     renders no element the selector could name;
+ *   - a node whose parent is ROOT, because the pointer is inside the page
+ *     whenever it is inside the window;
+ *   - an orphan whose parent id points at nothing.
+ */
+export function hoverHostOf(doc, id) {
+    const node = doc.nodes[id];
+    const parentId = node?.data.parent;
+    if (!node || !parentId)
+        return null;
+    const parent = doc.nodes[parentId];
+    if (!parent || !(parent.data.nodes ?? []).includes(id))
+        return null;
+    if (parent.data.type === 'root' || parentId === doc.root_node_id)
+        return null;
+    return parentId;
+}
+/** Is this node a satellite — referenced from its parent's config, not its children? */
+export function isSatelliteNode(doc, id) {
+    const parentId = doc.nodes[id]?.data.parent;
+    if (!parentId)
+        return false;
+    const parent = doc.nodes[parentId];
+    return !!parent && !(parent.data.nodes ?? []).includes(id);
+}
+/**
+ * Refuse a parent-hover override that no selector would ever match, naming which
+ * of the three reasons applies — the caller is one structural fact away from the
+ * design they wanted, and "it does nothing" would not tell them which.
+ */
+export function requireHoverHost(doc, id) {
+    if (hoverHostOf(doc, id))
+        return;
+    if (isSatelliteNode(doc, id)) {
+        throw new Error(`sbuilder: "${PARENT_HOVER_STATE}" needs a box to hover, and ${id} is a SATELLITE — it ` +
+            'hangs off its owner\'s config rather than its children and renders no element of its ' +
+            'own, so there is nothing for the rule to name. Style its own hover instead ' +
+            `(state: "${HOVER_STATE}"), which its owner compiles.`);
+    }
+    const parentId = doc.nodes[id]?.data.parent;
+    if (!parentId) {
+        throw new Error(`sbuilder: ${id} has no parent, so "${PARENT_HOVER_STATE}" has nothing to key off.`);
+    }
+    throw new Error(`sbuilder: "${PARENT_HOVER_STATE}" keys off the node's PARENT, and ${id}'s parent is ROOT — ` +
+        'the pointer is inside the page whenever it is inside the window, so the platform emits ' +
+        'no rule. Put this node inside a real box (a section\'s inner block, a card) and set it ' +
+        `there, or use state: "${HOVER_STATE}" for the node's own pointer state.`);
+}
+/**
+ * The one config key a hover state translates into a declaration, and only
+ * `true` — the same contract `stuckDecls` has, for the same reason: `false`
+ * would need `display: revert`, which rolls past the element's own static CSS to
+ * the UA default.
+ */
+export function refuseHoverConfig(keys, state) {
+    const stray = Object.keys(keys).filter((k) => k !== 'hidden');
+    if (stray.length) {
+        throw new Error(`sbuilder: the "${state}" state translates exactly one config key — "hidden" — into a ` +
+            `declaration (display:none). ${stray.map((k) => `"${k}"`).join(', ')} would be stored ` +
+            'and read by no compiler. Style is what a state paints.');
+    }
+    if ('hidden' in keys && keys.hidden !== true) {
+        throw new Error(`sbuilder: "${state}" config.hidden takes only true. false would have to mean "show it ` +
+            'again while hovered", which needs display:revert — wrong here, because revert rolls ' +
+            "past the element's own static CSS to the UA default. To stop hiding it, remove the " +
+            'override.');
+    }
+}
+/**
+ * Refuse a reveal that compiles to nothing.
+ *
+ * `compileHoverCss` emits the reveal pair only `if (hostScope && …)`, so the
+ * switch on a satellite or a top-level section is stored and the element simply
+ * stays visible — the caller asked for a quick-add button that appears on hover
+ * and got one that is always there, with nothing to say so.
+ */
+export function refuseReveal(doc, id, keys) {
+    if (keys[REVEAL_ON_HOVER] !== true)
+        return;
+    if (hoverHostOf(doc, id))
+        return;
+    throw new Error(`sbuilder: config.${REVEAL_ON_HOVER} hides this until the box AROUND it is hovered, and ` +
+        `${id} has no such box (a satellite, or a direct child of ROOT). The platform emits ` +
+        'neither half of the reveal, so the element would simply stay visible. Put it inside a ' +
+        'card or a block and set it there.');
+}
+/**
+ * The note a caller gets when a hover write is routed somewhere other than
+ * `states.hover`, and the warning when nothing will read it either way.
+ *
+ * Said rather than silently done: the routing is right, but a caller who later
+ * reads the node back would otherwise find their keys somewhere they did not put
+ * them.
+ */
+export function hoverRoutingNote(type) {
+    if (HOVER_UNCOMPILED.has(type)) {
+        return (`"${type}" declares a Hover variant, so the platform's universal hover compiler stands ` +
+            'aside for it — and measured on 2026-09-09, no element-specific compiler picks the slot ' +
+            'up either, so this override paints nothing. Written where its meta says it belongs ' +
+            '(states.hover), which is where it will start painting when the platform closes the gap. ' +
+            'Style a wrapper around it if the hover has to be visible now.');
+    }
+    if (hoverHome(type) !== 'legacy')
+        return null;
+    return (`"${type}" stores its hover in config.${LEGACY_HOVER_KEY} — a flat map its own renderer ` +
+        'compiles into the node\'s :hover rule — and the universal hover state stands aside for it, ' +
+        'so states.hover here would be read by nobody. Written to that map instead. It is BASE-ONLY, ' +
+        'so this value applies at every width.');
+}
+/** The path a legacy hover write lands on — flat, base-only, one key per patch. */
+export function legacyHoverPath(id, key) {
+    return ['nodes', id, 'config', LEGACY_HOVER_KEY, key];
+}

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

@@ -15,6 +15,7 @@ import { globalWarning, restampPatches, RESPONSIVE_NOTICE } from '../domains/sit
 import { catalogMatches, traitsFor } from '../catalog/element-search.js';
 import { applyPatches } from '../core/patch.js';
 import { stickyWarning } from '../domains/site/sticky.js';
+import { HOVER_STATE, hoverRoutingNote } from '../domains/site/hover.js';
 import { siteFor } from './context.js';
 import { projectList, PAGE_FIELDS, TEMPLATE_FIELDS } from './project.js';
 /**
@@ -262,6 +263,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,22 +284,38 @@ 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);
+        // WHERE A HOVER ACTUALLY WENT. Routing it silently would leave a caller
+        // who reads the node back looking for keys in a slot they never wrote to —
+        // and, for the elements with no compiler on either home, believing they
+        // had styled something.
+        const hoverNotes = {};
+        for (const e of batch) {
+            if (e.state !== HOVER_STATE || e.namespace !== 'style')
+                continue;
+            const note = hoverRoutingNote(d.doc.nodes[e.id]?.data.type ?? '');
+            if (note)
+                hoverNotes[e.id] = note;
+        }
         // THE STICKY WARNING IS COMPUTED AGAINST THE DOCUMENT AS IT WILL BE, so
         // the dry run and the real run say the same thing. A caller who is told
         // only after committing has already shipped a header that does not move.
@@ -324,6 +346,7 @@ export function registerPageTools(server, ctx) {
                 dry_run: true,
                 patches,
                 ...(Object.keys(sw).length ? { warnings: sw } : {}),
+                ...(Object.keys(hoverNotes).length ? { hover: hoverNotes } : {}),
                 ...(note ? { note } : {}),
             });
         }
@@ -337,9 +360,20 @@ export function registerPageTools(server, ctx) {
         }
         if (!edits) {
             const warn = warnings[batch[0].id];
-            return text({ set: touched[0].keys, rev: d.rev, ...(warn ? { warning: warn } : {}) });
+            const hv = hoverNotes[batch[0].id];
+            return text({
+                set: touched[0].keys,
+                rev: d.rev,
+                ...(warn ? { warning: warn } : {}),
+                ...(hv ? { hover: hv } : {}),
+            });
         }
-        return text({ set: touched, rev: d.rev, ...(Object.keys(warnings).length ? { warnings } : {}) });
+        return text({
+            set: touched,
+            rev: d.rev,
+            ...(Object.keys(warnings).length ? { warnings } : {}),
+            ...(Object.keys(hoverNotes).length ? { hover: hoverNotes } : {}),
+        });
     });
     server.registerTool('sb_move', {
         description: 'Move a node to another parent at an index.',

package/package.json

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