sbuilder-mcp 0.11.3 → 0.13.0

package/CHANGELOG.md

@@ -6,6 +6,20 @@ 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.13.0] - 2026-09-09
+
+### Added
+- sb_set now accepts `specials.hoverHostDepth` on a `state:"parentHover"` write, letting a rule hang off any ancestor box (1-based, nearest-first) instead of always the node's immediate parent, and reports which box it actually hung off, the wider ancestors on offer, and whether a depth past the end of the chain clamped to the outermost one.
+- Element catalog refreshed to 109 elements, adding `cart-count` and a `hoverSwapImage` option on `product-image-feature` (shows the next gallery photo on pointer-hover, off by default).
+
+## [0.12.0] - 2026-09-09
+
+### Added
+- npm run codegen:check now also refuses a checkout whose HEAD carries commits touching the directories it reads (schema/src, editor/src, server/render, server/docs) that its upstream branch does not have, naming the commits; an uncommitted-only check had already been fooled once, by a feature committed locally and never pushed, so the tree read clean while the catalog it fed was ahead of every deployed platform. A detached worktree checked out at origin/main has no upstream and is therefore exempt, which is the shape the check itself recommends; `--dirty` still overrides it.
+
+### Fixed
+- The generated request-shape catalog now covers three write operations its handler parser was missing or mis-attributing: `roles/{roleId}` (a case arm listing several HTTP methods together), `products/{productId}/categories` (a dispatcher that routes by a literal path segment rather than by method), and `sites/{siteId}/org` (a doc comment block shared by two adjacent handlers declared in the opposite order, now attributed by the name it opens with). 162 of 276 write operations now carry a shape, up from 157, so sb_api_call and sb_undo can act on all three without guessing a body.
+
 ## [0.11.3] - 2026-09-09
 
 ### Fixed

package/CHANGELOG.vi.md

@@ -6,6 +6,20 @@ 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.13.0] - 2026-09-09
+
+### Added
+- sb_set giờ hỗ trợ `specials.hoverHostDepth` khi ghi `state:"parentHover"`, cho phép một rule hover-cha hangs off bất kỳ ancestor box nào (đánh số từ 1, gần nhất trước) thay vì luôn luôn là parent trực tiếp của node, và trả về box mà nó thực sự hangs off, các ancestor rộng hơn đang có sẵn, cùng thông báo khi một depth vượt quá độ dài chuỗi bị clamp về box ngoài cùng.
+- Catalog element được làm mới lên 109 element, thêm `cart-count` và tùy chọn `hoverSwapImage` trên `product-image-feature` (hiện ảnh gallery kế tiếp khi trỏ chuột vào, mặc định tắt).
+
+## [0.12.0] - 2026-09-09
+
+### Added
+- npm run codegen:check giờ cũng từ chối một checkout mà HEAD của nó mang các commit chạm vào những thư mục mà nó đọc (schema/src, editor/src, server/render, server/docs) mà nhánh upstream không có, nêu tên các commit đó; việc chỉ kiểm tra thay đổi chưa commit từng bị qua mặt một lần, bởi một tính năng đã được commit ở local nhưng chưa từng push, khiến working tree trông sạch trong khi catalog mà nó tạo ra lại đi trước mọi nền tảng đã triển khai. Một worktree tách rời checkout tại origin/main không có upstream nên được miễn kiểm tra này, đúng như cách mà chính kiểm tra này khuyến nghị; `--dirty` vẫn cho phép ghi đè.
+
+### Fixed
+- Catalog request-shape được sinh ra giờ bao phủ thêm ba write operation mà trình phân tích handler trước đây bỏ sót hoặc gán sai: `roles/{roleId}` (một case arm liệt kê nhiều phương thức HTTP cùng lúc), `products/{productId}/categories` (một dispatcher định tuyến theo một đoạn path cố định thay vì theo method), và `sites/{siteId}/org` (một khối doc comment dùng chung cho hai handler liền kề được khai báo theo thứ tự ngược lại, giờ được gán theo đúng tên mà nó mở đầu). 162 trong số 276 write operation giờ đã có shape, tăng từ 157, nhờ đó sb_api_call và sb_undo có thể thao tác trên cả ba mà không cần đoán body.
+
 ## [0.11.3] - 2026-09-09
 
 ### Fixed

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",
@@ -13909,7 +14071,7 @@ export const ELEMENTS = {
                         "controls": [
                             "font_family",
                             "font_size",
-                            "font_weight",
+                            "text_style",
                             "text_color"
                         ]
                     },
@@ -13972,7 +14134,7 @@ export const ELEMENTS = {
             "horizontal",
             "font_family",
             "font_size",
-            "font_weight",
+            "text_style",
             "text_color",
             "bg_color",
             "border",
@@ -14330,7 +14492,8 @@ export const ELEMENTS = {
                 "paginationItemWidth": 8,
                 "paginationItemHeight": 8,
                 "paginationItemGap": 4,
-                "featureClickAction": "open_gallery"
+                "featureClickAction": "open_gallery",
+                "hoverSwapImage": false
             },
             "specials": {
                 "alt": ""
@@ -16332,6 +16495,7 @@ export const ELEMENTS = {
                             "image_alt",
                             "main_image_source",
                             "feature_zoom",
+                            "feature_hover_swap",
                             "feature_click_action",
                             "feature_nav",
                             "feature_dots",
@@ -16354,6 +16518,7 @@ export const ELEMENTS = {
                             "listNavButtonBg",
                             "hoverZoomType",
                             "hoverZoomValue",
+                            "hoverSwapImage",
                             "paginationBg",
                             "paginationItemBg",
                             "paginationItemActiveBg",
@@ -16439,6 +16604,7 @@ export const ELEMENTS = {
             "image_alt",
             "main_image_source",
             "feature_zoom",
+            "feature_hover_swap",
             "feature_click_action",
             "feature_nav",
             "feature_dots",
@@ -16461,6 +16627,7 @@ export const ELEMENTS = {
             "listNavButtonBg",
             "hoverZoomType",
             "hoverZoomValue",
+            "hoverSwapImage",
             "paginationBg",
             "paginationItemBg",
             "paginationItemActiveBg",
@@ -16486,7 +16653,7 @@ export const ELEMENTS = {
             "animation",
             "class_css"
         ],
-        "description": "A large product feature image carousel — stacks its images and shows the active one at full size, with optional prev/next navigation, pagination dots, and hover-zoom on published pages. When pinned to (or placed under) a product it carousels that product's full image gallery (config.mainImageSource picks which image leads), falling back to the seeded config.images when unbound. Owns no children.",
+        "description": "A large product feature image carousel — stacks its images and shows the active one at full size, with optional prev/next navigation, pagination dots, hover-zoom and a hover image swap (config.hoverSwapImage) on published pages. When pinned to (or placed under) a product it carousels that product's full image gallery (config.mainImageSource picks which image leads), falling back to the seeded config.images when unbound. Owns no children.",
         "useWhen": [
             "Showing the primary/large product photo on a product detail layout.",
             "You want visitors to page through several product images."
@@ -16499,7 +16666,8 @@ export const ELEMENTS = {
             "Pair it with an Image list so shoppers can pick which photo shows large.",
             "Use a consistent image ratio (config.featureImageRatio) so the layout does not jump between images — default is a uniform 1:1 square; \"auto\" uses each image's natural size.",
             "Hover-zoom is on by default at 150% (config.hoverZoomValue); set it to 100 to disable, or raise it up to 300 for a closer zoom.",
-            "Nav arrows sit \"inside\" (overlaid) or \"outside\" the image via config.listNavPosition."
+            "Nav arrows sit \"inside\" (overlaid) or \"outside\" the image via config.listNavPosition.",
+            "config.hoverSwapImage shows the NEXT gallery photo while the pointer is on the tile — the product-grid effect. It needs a gallery of 2+, is off by default, and does nothing on a touch screen (no pointer), so a phone keeps the first photo."
         ],
         "semantics": [
             "product-image",
@@ -33572,6 +33740,17 @@ export const TRAIT_WRITES = {
             }
         ]
     },
+    "feature_hover_swap": {
+        "key": "feature_hover_swap",
+        "label": "Image swap",
+        "writes": [
+            {
+                "target": "config",
+                "writeKey": "hoverSwapImage",
+                "type": "boolean"
+            }
+        ]
+    },
     "overflow_x": {
         "key": "overflow_x",
         "label": "Overflow X",
@@ -33677,6 +33856,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",
@@ -34037,6 +34238,13 @@ export const TRAIT_WRITES = {
     }
 };
 export const SATELLITE_RULES = {
+    "icon": [
+        {
+            "type": "cart-count",
+            "configKey": "cartCountId",
+            "optional": true
+        }
+    ],
     "tab": [
         {
             "type": "tab-item",

package/dist/catalog/shapes.generated.js

@@ -1,7 +1,7 @@
 export const SHAPE_SOURCE = {
     "writeOperations": 212,
-    "shaped": 157,
-    "fromHandlers": 157,
+    "shaped": 162,
+    "fromHandlers": 162,
     "fromSwaggerOnly": 0,
     "withReadOnly": 26,
     "structsRead": 1597
@@ -171,6 +171,110 @@ export const REQUEST_SHAPES = {
         "source": "go",
         "goType": "versionInput"
     },
+    "post:/api/orgs/{orgId}/apps/{appId}/versions/{versionId}/withdraw": {
+        "fields": [
+            {
+                "name": "version",
+                "type": "string"
+            },
+            {
+                "name": "scopes",
+                "type": "string[]"
+            },
+            {
+                "name": "embedUrl",
+                "type": "string"
+            },
+            {
+                "name": "redirectUri",
+                "type": "string"
+            },
+            {
+                "name": "summary",
+                "type": "string"
+            },
+            {
+                "name": "description",
+                "type": "string"
+            },
+            {
+                "name": "category",
+                "type": "string",
+                "note": "Category is the marketplace shelf, from apps."
+            },
+            {
+                "name": "pricingModel",
+                "type": "string",
+                "note": "PricingModel, PriceCents, PriceCurrency and BillingInterval are what this version costs a merchant. THIS ROUTE IS A FULL REPLACEMENT, and that includes the price: a client that omits `pricingModel` is saying free, exactly as one that…"
+            },
+            {
+                "name": "priceCents",
+                "type": "number"
+            },
+            {
+                "name": "priceCurrency",
+                "type": "string"
+            },
+            {
+                "name": "billingInterval",
+                "type": "string"
+            }
+        ],
+        "source": "go",
+        "goType": "versionInput"
+    },
+    "post:/api/orgs/{orgId}/apps/{appId}/versions/{versionId}/images": {
+        "fields": [
+            {
+                "name": "version",
+                "type": "string"
+            },
+            {
+                "name": "scopes",
+                "type": "string[]"
+            },
+            {
+                "name": "embedUrl",
+                "type": "string"
+            },
+            {
+                "name": "redirectUri",
+                "type": "string"
+            },
+            {
+                "name": "summary",
+                "type": "string"
+            },
+            {
+                "name": "description",
+                "type": "string"
+            },
+            {
+                "name": "category",
+                "type": "string",
+                "note": "Category is the marketplace shelf, from apps."
+            },
+            {
+                "name": "pricingModel",
+                "type": "string",
+                "note": "PricingModel, PriceCents, PriceCurrency and BillingInterval are what this version costs a merchant. THIS ROUTE IS A FULL REPLACEMENT, and that includes the price: a client that omits `pricingModel` is saying free, exactly as one that…"
+            },
+            {
+                "name": "priceCents",
+                "type": "number"
+            },
+            {
+                "name": "priceCurrency",
+                "type": "string"
+            },
+            {
+                "name": "billingInterval",
+                "type": "string"
+            }
+        ],
+        "source": "go",
+        "goType": "versionInput"
+    },
     "post:/api/sites/{siteId}/quizzes": {
         "fields": [
             {
@@ -1790,7 +1894,7 @@ export const REQUEST_SHAPES = {
         "source": "go",
         "goType": "courses.Course"
     },
-    "put:/api/sites/{siteId}/courses/{courseId}/sections/{sectionId}": {
+    "post:/api/sites/{siteId}/courses/{courseId}/sections": {
         "fields": [
             {
                 "name": "id",
@@ -1833,7 +1937,7 @@ export const REQUEST_SHAPES = {
         "source": "go",
         "goType": "courses.Section"
     },
-    "post:/api/sites/{siteId}/courses/{courseId}/sections": {
+    "put:/api/sites/{siteId}/courses/{courseId}/sections/{sectionId}": {
         "fields": [
             {
                 "name": "id",
@@ -1876,7 +1980,7 @@ export const REQUEST_SHAPES = {
         "source": "go",
         "goType": "courses.Section"
     },
-    "put:/api/sites/{siteId}/courses/{courseId}/lessons/{lessonId}": {
+    "post:/api/sites/{siteId}/courses/{courseId}/lessons": {
         "fields": [
             {
                 "name": "id",
@@ -1972,7 +2076,7 @@ export const REQUEST_SHAPES = {
         "source": "go",
         "goType": "courses.Lesson"
     },
-    "post:/api/sites/{siteId}/courses/{courseId}/lessons": {
+    "put:/api/sites/{siteId}/courses/{courseId}/lessons/{lessonId}": {
         "fields": [
             {
                 "name": "id",
@@ -4762,10 +4866,10 @@ export const REQUEST_SHAPES = {
             "updatedAt"
         ]
     },
-    "put:/api/sites/{siteId}/product-categories/{id}/products": {
+    "put:/api/sites/{siteId}/products/{productId}/categories": {
         "fields": [
             {
-                "name": "productIds",
+                "name": "categoryIds",
                 "type": "string[]"
             }
         ],
@@ -4782,6 +4886,16 @@ export const REQUEST_SHAPES = {
         "source": "go",
         "goType": "(inline)"
     },
+    "put:/api/sites/{siteId}/product-categories/{id}/products": {
+        "fields": [
+            {
+                "name": "productIds",
+                "type": "string[]"
+            }
+        ],
+        "source": "go",
+        "goType": "(inline)"
+    },
     "post:/api/sites/{siteId}/product-categories": {
         "fields": [
             {
@@ -6337,6 +6451,30 @@ export const REQUEST_SHAPES = {
         "source": "go",
         "goType": "(inline)"
     },
+    "put:/api/sites/{siteId}/roles/{roleId}": {
+        "fields": [
+            {
+                "name": "name",
+                "type": "string"
+            },
+            {
+                "name": "permissions",
+                "type": "site.Permission[]"
+            }
+        ],
+        "source": "go",
+        "goType": "(inline)"
+    },
+    "put:/api/sites/{siteId}/org": {
+        "fields": [
+            {
+                "name": "orgId",
+                "type": "string"
+            }
+        ],
+        "source": "go",
+        "goType": "(inline)"
+    },
     "put:/api/sites/{id}/owner": {
         "fields": [
             {

package/dist/domains/site/hover.js

@@ -72,11 +72,22 @@ export function hoverHome(type) {
  */
 const HOVER_UNCOMPILED = new Set(['product-image-list']);
 /**
- * The box whose `:hover` a parent-hover rule keys off, or null.
+ * The specials key naming WHICH ancestor a parent-hover rule hangs off, 1-based
+ * and nearest-first. Base-only: it is identity, not a quantity, and a host that
+ * differed per breakpoint would compile one state slot against different
+ * selectors at different widths.
+ *
+ * Absent means 1 — the node's own parent — which is what the seeded product card
+ * wants, because that template is flat and a child's parent IS the card. The key
+ * exists for the moment an author groups a few things inside it: the nearest box
+ * becomes the group, and "hover the whole card" stops being reachable without it.
+ */
+export const HOVER_HOST_DEPTH = 'hoverHostDepth';
+/**
+ * Every ancestor a parent-hover state could hang off, NEAREST FIRST.
  *
- * 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:
+ * Mirrors `hoverHostChain`. Empty for the three cases that can host nothing, 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;
@@ -84,17 +95,57 @@ const HOVER_UNCOMPILED = new Set(['product-image-list']);
  *     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;
+export function hoverHostChain(doc, id) {
+    if (!hasHoverableBox(doc, id))
+        return [];
+    const out = [];
+    const seen = new Set([id]);
+    let cur = doc.nodes[id];
+    for (;;) {
+        const parentId = cur?.data.parent;
+        if (!parentId || seen.has(parentId))
+            break;
+        seen.add(parentId);
+        const parent = doc.nodes[parentId];
+        if (!parent || parent.data.type === 'root' || parentId === doc.root_node_id)
+            break;
+        out.push(parentId);
+        cur = parent;
+    }
+    return out;
+}
+/** Does this node have a box of its own — a real child of a real parent? */
+function hasHoverableBox(doc, id) {
+    const parentId = doc.nodes[id]?.data.parent;
+    if (!parentId)
+        return false;
     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 !!parent && (parent.data.nodes ?? []).includes(id);
+}
+/** The stored depth, coerced the way the platform coerces it: anything that is
+ * not a whole number ≥ 1 reads as 1, so a corrupt value costs the author the
+ * ancestor they picked rather than the whole state. */
+export function hoverHostDepthOf(doc, id) {
+    const raw = doc.nodes[id]?.specials?.[HOVER_HOST_DEPTH];
+    const n = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isFinite(n) || n < 1)
+        return 1;
+    return Math.floor(n);
+}
+/**
+ * The box whose `:hover` a parent-hover rule keys off, or null.
+ *
+ * The node's PARENT by default, or the ancestor `hoverHostDepth` levels up when
+ * the document names one. A depth past the end of the chain CLAMPS to the
+ * outermost real ancestor rather than answering null — the chain shortens
+ * whenever a wrapper is deleted, and a state pointing one level out is better
+ * than one that silently goes dead.
+ */
+export function hoverHostOf(doc, id) {
+    const chain = hoverHostChain(doc, id);
+    if (!chain.length)
         return null;
-    return parentId;
+    return chain[Math.min(hoverHostDepthOf(doc, id), chain.length) - 1];
 }
 /** Is this node a satellite — referenced from its parent's config, not its children? */
 export function isSatelliteNode(doc, id) {
@@ -122,11 +173,43 @@ export function requireHoverHost(doc, id) {
     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 — ` +
+    throw new Error(`sbuilder: "${PARENT_HOVER_STATE}" hangs off an ANCESTOR BOX, and ${id}'s only one 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.`);
 }
+/**
+ * WHICH BOX A PARENT-HOVER RULE ACTUALLY HUNG OFF, said out loud.
+ *
+ * The inspector has a picker and a label that name it; an agent has neither, and
+ * the default — the NEAREST box — is the wrong one the moment somebody groups a
+ * few things inside a card. Writing the state and being told nothing is how a
+ * "hover the card" effect ends up triggered by an inner wrapper instead.
+ *
+ * Also reports a depth that CLAMPED, which the platform does silently: past the
+ * end of the chain it falls back to the outermost ancestor rather than going
+ * dead, so the caller's number and the box they got can differ with nothing on
+ * screen to say so.
+ */
+export function hoverHostNote(doc, id) {
+    const chain = hoverHostChain(doc, id);
+    if (!chain.length)
+        return null;
+    const want = hoverHostDepthOf(doc, id);
+    const got = Math.min(want, chain.length);
+    const host = chain[got - 1];
+    const named = (n) => `${doc.nodes[n]?.data.name ?? doc.nodes[n]?.data.type ?? '?'} ${n}`;
+    if (want > chain.length) {
+        return (`Hangs off ${named(host)} — specials.${HOVER_HOST_DEPTH} asks for level ${want} and the ` +
+            `chain is ${chain.length} long, so the platform CLAMPED to the outermost box. Set the ` +
+            'depth to a level that exists, or accept this one.');
+    }
+    if (chain.length === 1)
+        return null; // no choice to get wrong
+    return (`Hangs off ${named(host)} (level ${got} of ${chain.length}). To hang it off a wider box — ` +
+        `the whole card rather than the group inside it — set specials.${HOVER_HOST_DEPTH}, ` +
+        `1-based and nearest-first: ${chain.map((n, i) => `${i + 1}=${named(n)}`).join(', ')}.`);
+}
 /**
  * The one config key a hover state translates into a declaration, and only
  * `true` — the same contract `stuckDecls` has, for the same reason: `false`

package/dist/tools/page.js

@@ -15,7 +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 { HOVER_STATE, PARENT_HOVER_STATE, hoverHostNote, hoverRoutingNote } from '../domains/site/hover.js';
 import { siteFor } from './context.js';
 import { projectList, PAGE_FIELDS, TEMPLATE_FIELDS } from './project.js';
 /**
@@ -321,6 +321,17 @@ export function registerPageTools(server, ctx) {
             if (hoverRoutingNote(type))
                 hoverTypes.add(type);
         }
+        // WHICH BOX a parent-hover rule hung off. Per NODE rather than once per
+        // process: the answer is about this node's ancestry, so a second node's is
+        // genuinely different information.
+        const hostNotes = {};
+        for (const e of batch) {
+            if (e.state !== PARENT_HOVER_STATE)
+                continue;
+            const n = hoverHostNote(d.doc, e.id);
+            if (n)
+                hostNotes[e.id] = n;
+        }
         const hoverNote = [...hoverTypes]
             .map((t) => ctx.notices.once(`hover-home:${t}`, hoverRoutingNote(t)))
             .filter((n) => !!n)
@@ -356,6 +367,7 @@ export function registerPageTools(server, ctx) {
                 patches,
                 ...(Object.keys(sw).length ? { warnings: sw } : {}),
                 ...(hoverNote ? { hover: hoverNote } : {}),
+                ...(Object.keys(hostNotes).length ? { hover_host: hostNotes } : {}),
                 ...(note ? { note } : {}),
             });
         }
@@ -374,6 +386,7 @@ export function registerPageTools(server, ctx) {
                 rev: d.rev,
                 ...(warn ? { warning: warn } : {}),
                 ...(hoverNote ? { hover: hoverNote } : {}),
+                ...(hostNotes[batch[0].id] ? { hover_host: hostNotes[batch[0].id] } : {}),
             });
         }
         return text({
@@ -381,6 +394,7 @@ export function registerPageTools(server, ctx) {
             rev: d.rev,
             ...(Object.keys(warnings).length ? { warnings } : {}),
             ...(hoverNote ? { hover: hoverNote } : {}),
+            ...(Object.keys(hostNotes).length ? { hover_host: hostNotes } : {}),
         });
     });
     server.registerTool('sb_move', {

package/package.json

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