sbuilder-mcp 0.76.4 → 0.77.0

package/CHANGELOG.md

@@ -6,6 +6,21 @@ 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.77.0] - 2026-10-08
+
+### Added
+- `sb_catalog_search` ranks exact type and name matches first, then whole words, then element keys and vocabulary values, so searches such as pagination, sort or load_more find the right element.
+- `sb_traits_for` reports `base_only`, `preconditions`, `events`, `binding_events` and `bindable` for an element, and marks controls that write base-only keys with `responsive:false`.
+- `sb_add` and `sb_set` return a `checks` list (`unknown_key`, `unknown_value`, `form_rule` and others) in place of `value`.
+- `sb_review` reports `invalid_action`, `action_missing_target`, `no_data_context` and `unread_value` findings, and returns the `custom_code_native` maintenance hint separately under `advice`.
+- `sb_page_open` with `form_id` edits a form's document fields, including fields, defaults and dependent-field rules, using a rule vocabulary generated from the platform.
+- `sb_undo` undoes and redoes page operations, and refuses when the undo would erase live edits.
+
+### Changed
+- `sb_bind` refuses a field that cannot be bound, and `sb_event` refuses an action with no target (url, popup id or `targetId`) unless `force` is set.
+- The `dry_run` of the eight writing tools runs the same validation step as a real save and returns `would_refuse`, without consuming warnings, and a `sb_template_use` dry run no longer changes the open page.
+- `scroll_to` projects an `href` of `#id` and checks `targetId`, waiting for the platform to release the matching change.
+
 ## [0.76.4] - 2026-10-08
 
 ### Added

package/CHANGELOG.vi.md

@@ -6,6 +6,21 @@ 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.77.0] - 2026-10-08
+
+### Added
+- `sb_catalog_search` xếp các kết quả trùng type và tên lên đầu, rồi đến từ nguyên vẹn, rồi key và giá trị từ vựng của element, nên tìm pagination, sort hay load_more ra đúng element.
+- `sb_traits_for` trả thêm `base_only`, `preconditions`, `events`, `binding_events` và `bindable` của element, và đánh dấu `responsive:false` trên control ghi key chỉ-base.
+- `sb_add` và `sb_set` trả danh sách `checks` (`unknown_key`, `unknown_value`, `form_rule` và các loại khác) thay cho `value`.
+- `sb_review` báo thêm các finding `invalid_action`, `action_missing_target`, `no_data_context` và `unread_value`, đồng thời trả gợi ý bảo trì `custom_code_native` riêng trong `advice`.
+- `sb_page_open` với `form_id` sửa các field document của form, gồm trường, giá trị mặc định và rule field phụ thuộc, dùng từ vựng rule sinh từ nền tảng.
+- `sb_undo` hoàn tác và làm lại các thao tác trên trang, và từ chối khi việc hoàn tác sẽ xoá các sửa đổi live.
+
+### Changed
+- `sb_bind` từ chối field không bind được, và `sb_event` từ chối action thiếu đích (url, id popup hoặc `targetId`) trừ khi đặt `force`.
+- `dry_run` của tám tool ghi chạy đúng bước validate của lần lưu thật và trả `would_refuse`, không tiêu cảnh báo, và `sb_template_use` ở chế độ dry run không còn đổi trang đang mở.
+- `scroll_to` chiếu `href` dạng `#id` và kiểm tra `targetId`, chờ nền tảng phát hành thay đổi tương ứng.
+
 ## [0.76.4] - 2026-10-08
 
 ### Added

package/README.md

@@ -84,7 +84,7 @@ in this client: one would put the very key the platform exists to hold back into
 | `sb_site_list` | List the sites this account can operate |
 | `sb_api_find` | Find API operations by intent — one line per match — then read one operation's call sheet by id: real parameter schemas, the credential it needs, and the body's fields read off the handler that decodes them, each carrying the trap its own doc comment records |
 | `sb_api_call` | Execute an operation, or any route by method+path; dry run by default. Field selection and local result pagination |
-| `sb_page_open` | Open a page for editing and return its outline |
+| `sb_page_open` | Open a page for editing and return its outline — or, with `form_id`, a form's field document (fields, defaults, dependent-field rules) |
 | `sb_outline` | The open page as a compressed tree — never a raw document dump |
 | `sb_node_read` | One node in full, with a warning if it is a shared global |
 | `sb_catalog_search` | Find an element by what it should do, using the platform's own AI hints |
@@ -112,7 +112,7 @@ in this client: one would put the very key the platform exists to hold back into
 | `sb_import_site` | Read a WHOLE site from one URL — its sitemap, or the links on that page — and give each page found its own draft page here, built from this site's tokens; the entry page's own colours and type scale also patch into this SITE'S theme, so it stops being purely a read |
 | `sb_theme` | Read or patch the site's palette and type scale — the layer every style preset resolves from, so one token repaints every page; `locale` sets the site's language |
 | `sb_store` | Run a store flow that must happen in a fixed order — `checkout` (the four writes that make a working one), `checkout_sync` (the store's current payment and delivery methods into every existing order form, checkout page republished), `form` (any of the platform's 17 templates with its own field document), `chrome` (one shared header or footer on a real site menu — desktop menu, mobile drawer, cart and account icons), `menu` (a menu node bound to the site's menu, its links resolved), `overlay_attach` (a pop-up or quick view on the open page), `cart` (the site's cart drawer, when it has none; `relocalize` puts an existing one in the site's language) and `app` (a built-in app plus the pages it needs), `global_attach` / `global_detach` (put an EXISTING shared section on the open page, or take it off) |
-| `sb_undo` | Put back what a PUT replaced. The SECOND answer for a page, not the only one: the platform has versions, history and restore (`sb_api_find` "page versions"), which outlive this process — reach for those first and use this for every other shaped PUT |
+| `sb_undo` | Undo / redo this session's writes — page and form edits and `sb_api_call` PUTs; a page is refused if someone else saved it since. The platform's versions and history (`sb_api_find` "page versions") outlive this process |
 
 Twenty-eight tools, **574 API operations** (197 of the 255 writes carrying a body shape read
 off the handler), 122 elements, 79 binding sources. `sb_api_find`
@@ -124,7 +124,7 @@ Every result is compact JSON, every directive is said once per process, and ever
 carries MCP annotations — a client that honours them stops asking a person to confirm a
 read.
 
-Full reference: [`docs/tools.md`](./docs/tools.md).
+Full reference: [`docs/tools.md`](./docs/tools.md). What the builder supports natively, and where it stops: [`docs/capabilities.md`](./docs/capabilities.md).
 
 ## How it stays in sync
 

package/README.vi.md

@@ -81,7 +81,7 @@ nhét ngược lại vào mọi bản cài.
 | `sb_site_list` | Liệt kê site tài khoản vận hành được |
 | `sb_api_find` | Tìm operation theo ý định — mỗi kết quả một dòng — rồi đọc call sheet của một operation theo id: schema tham số thật, credential cần dùng, và các trường body đọc thẳng từ handler decode chúng, mỗi trường mang theo cái bẫy doc comment của chính nó ghi lại |
 | `sb_api_call` | Chạy operation, hoặc bất kỳ route nào bằng method+path; mặc định chạy khô. Chọn field và phân trang kết quả phía MCP |
-| `sb_page_open` | Mở một trang để sửa và trả về outline |
+| `sb_page_open` | Mở một trang để sửa và trả về outline — hoặc, với `form_id`, tài liệu trường của biểu mẫu (trường, giá trị mặc định, quy tắc trường phụ thuộc) |
 | `sb_outline` | Trang đang mở dạng cây nén — không bao giờ dump tài liệu thô |
 | `sb_node_read` | Một node đầy đủ, kèm cảnh báo nếu nó là global dùng chung |
 | `sb_catalog_search` | Tìm element theo việc nó cần làm, dùng chính AI hints của nền tảng |
@@ -109,7 +109,7 @@ nhét ngược lại vào mọi bản cài.
 | `sb_import_site` | Đọc CẢ website từ một URL — sitemap của nó, hoặc các link trên trang đó — và tạo cho mỗi trang tìm được một trang nháp riêng ở đây, dựng bằng token của site này; màu và thang chữ của trang gốc cũng được vá vào THEME của site này, nên đây không còn thuần là đọc |
 | `sb_theme` | Đọc hoặc vá bảng màu và thang chữ của site — tầng mà mọi style preset phân giải từ đó, nên một token thay áo cho mọi trang; `locale` đặt ngôn ngữ của site |
 | `sb_store` | Chạy một luồng cửa hàng bắt buộc đúng thứ tự — `checkout` (bốn lệnh ghi tạo nên trang thanh toán), `checkout_sync` (đưa phương thức thanh toán và giao hàng hiện tại vào mọi form đặt hàng đã có, publish lại trang thanh toán), `form` (một trong 17 template của nền tảng kèm field document của nó), `chrome` (một header hoặc footer dùng chung trên menu thật của site — menu desktop, drawer mobile, icon giỏ hàng và tài khoản), `menu` (một node menu bind vào menu của site, link đã phân giải), `overlay_attach` (một pop-up hay quick view trên trang đang mở), `cart` (ngăn giỏ hàng của site, khi chưa có; `relocalize` đưa ngăn giỏ đã có về ngôn ngữ của site), `app` (một app dựng sẵn kèm những trang nó cần), và `global_attach` / `global_detach` (đặt một section dùng chung ĐÃ CÓ lên trang đang mở, hoặc gỡ ra) |
-| `sb_undo` | Trả lại thứ mà một lệnh PUT đã ghi đè. Với TRANG thì đây là đường về thứ hai chứ không phải duy nhất: nền tảng có version, history và restore (`sb_api_find` "page versions"), và chúng sống lâu hơn tiến trình này — hãy dùng chúng trước, còn tool này cho mọi PUT có hình dạng khác |
+| `sb_undo` | Hoàn tác / làm lại các thao tác ghi trong phiên — chỉnh sửa trang, form và PUT qua `sb_api_call`; trang bị từ chối nếu người khác đã lưu sau đó. Version và history của nền tảng (`sb_api_find` "page versions") sống lâu hơn process này |
 
 Hai mươi tám tool, **574 operation API** (197 trong 255 lệnh ghi có hình dạng body đọc thẳng
 từ handler), 122 element, 79 nguồn binding. `sb_api_find` là
@@ -120,7 +120,7 @@ thứ nền tảng làm được vẫn với tới — và operation mới thêm
 Mọi kết quả đều là JSON nén, mọi directive chỉ nói một lần mỗi process, và mọi tool đều mang
 MCP annotation — client nào tôn trọng chúng sẽ thôi hỏi người dùng xác nhận một lần đọc.
 
-Tra cứu đầy đủ: [`docs/tools.vi.md`](./docs/tools.vi.md).
+Tra cứu đầy đủ: [`docs/tools.vi.md`](./docs/tools.vi.md). Builder hỗ trợ native những gì, và dừng ở đâu: [`docs/capabilities.vi.md`](./docs/capabilities.vi.md).
 
 ## Cách nó không bị lệch
 

package/dist/catalog/element-search.js

@@ -1,4 +1,6 @@
-import { ELEMENTS, TRAIT_WRITES } from './elements.generated.js';
+import { ELEMENTS, TRAIT_WRITES, WRITE_PRECONDITIONS } from './elements.generated.js';
+import { isBaseOnlyConfig } from '../domains/site/baseonly.js';
+import { bindableFields } from '../domains/site/writecheck.js';
 import { animationValues, animationVocabulary, elementVocabularies, sharedVocabularies, vocabulariesForWrites, } from '../domains/site/vocabulary.js';
 import { neverTranslatedOn, translatableSpecials } from '../domains/site/translate.js';
 /** Eight to choose from; the hints for the chosen one come with sb_traits_for. */
@@ -48,6 +50,81 @@ export function catalogBrowse() {
 export function largestCategorySize() {
     return Math.max(...Object.values(catalogBrowse()).map((g) => g.length));
 }
+/** Lowercase, diacritics off, camelCase and snake_case split — the unit a word match compares. */
+function words(s) {
+    return s
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+}
+/** Two spellings of one name compare equal: "Product list", "product-list", "PRÓDUCT LÍST". */
+const slug = (s) => words(s).join('-');
+/**
+ * CAPABILITY is the element's own generated config/specials keys and the
+ * vocabulary VALUES they take — so "pagination", "load_more" and "sort" find
+ * the element that does them from the shared metadata, with no alias table to
+ * drift. The weakest word signal, because a key name is not a purpose.
+ */
+let index = null;
+function searchIndex() {
+    return (index ??= Object.values(ELEMENTS).map((el) => {
+        const cap = [
+            ...Object.keys(el.defaults?.config ?? {}),
+            ...Object.keys(el.defaults?.specials ?? {}),
+            ...Object.values(elementVocabularies(el.type)).flatMap((v) => [v.writeKey, ...v.values]),
+        ];
+        const hints = [...el.semantics, ...el.useWhen];
+        return {
+            el,
+            ix: {
+                type: el.type,
+                label: slug(el.label),
+                typeWords: new Set(words(el.type)),
+                labelWords: new Set(words(el.label)),
+                hintWords: new Set(words(hints.join(' '))),
+                descWords: new Set(words(`${el.category} ${el.description}`)),
+                capWords: new Set(words(cap.join(' '))),
+                hay: words([el.type, el.label, el.category, el.description, ...hints].join(' ')).join(' '),
+            },
+        };
+    }));
+}
+/** A whole word, or its plural — "image" finds "images" without a stemmer. */
+const has = (set, t) => set.has(t) || set.has(`${t}s`);
+/**
+ * Tiered, so a stronger signal is never outvoted by a pile of weaker ones:
+ * exact type > exact label > the type's own words > the label's > semantics and
+ * useWhen > description > capability > bare substring. Measured before this:
+ * "list" returned address-book first and not `list` at all, because a flat
+ * substring count over prose ranks whatever mentions a word most.
+ */
+function score(ix, q, terms) {
+    let s = 0;
+    if (ix.type === q)
+        s += 1e6;
+    if (ix.label === q)
+        s += 1e5;
+    if (ix.type.startsWith(q))
+        s += 1e4;
+    for (const t of terms) {
+        if (has(ix.typeWords, t))
+            s += 1000;
+        if (has(ix.labelWords, t))
+            s += 300;
+        if (has(ix.hintWords, t))
+            s += 30;
+        if (has(ix.descWords, t))
+            s += 10;
+        if (has(ix.capWords, t))
+            s += 3;
+        if (ix.hay.includes(t))
+            s += 1;
+    }
+    return s;
+}
 /**
  * Four fields to CHOOSE by.
  *
@@ -57,14 +134,10 @@ export function largestCategorySize() {
  * `traitsFor` now carries. `detail: true` restores the hints per match.
  */
 export function catalogMatches(query, opts = {}) {
-    const terms = query.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
-    return Object.values(ELEMENTS)
-        .map((el) => {
-        const hay = [el.type, el.label, el.category, el.description, ...el.semantics, ...el.useWhen]
-            .join(' ')
-            .toLowerCase();
-        return { el, score: terms.filter((t) => hay.includes(t)).length };
-    })
+    const terms = words(query);
+    const q = terms.join('-');
+    return searchIndex()
+        .map(({ el, ix }) => ({ el, score: score(ix, q, terms) }))
         .filter((s) => s.score > 0)
         .sort((a, b) => b.score - a.score || a.el.type.localeCompare(b.el.type))
         .slice(0, opts.limit ?? DEFAULT_CATALOG_LIMIT)
@@ -83,7 +156,7 @@ export function catalogMatches(query, opts = {}) {
 /**
  * What one inspector control writes.
  *
- * 118 of the 435 controls declare it in the platform's trait registry. The rest
+ * 165 of the 577 controls declare it in the platform's trait registry. The rest
  * live inside a Vue widget's prop closure, which is not machine-readable — so
  * they come back named but undescribed, with the honest reason. Saying nothing
  * would read as "this control writes nothing".
@@ -125,10 +198,23 @@ export function traitsFor(type, control) {
         }
         return { type, control, ...describeControl(control) };
     }
+    // Read from base only whatever breakpoint is asked for — sb_set routes them
+    // there, so a "tablet-only" value of one of these is the desktop value too.
+    const baseOnly = [
+        ...new Set([
+            ...Object.keys(el.defaults?.config ?? {}),
+            ...el.controls.flatMap((c) => (TRAIT_WRITES[c]?.writes ?? []).filter((w) => w.target === 'config').map((w) => w.writeKey)),
+        ]),
+    ].filter((k) => isBaseOnlyConfig(type, k));
     const declared = {};
-    for (const c of el.controls)
-        if (TRAIT_WRITES[c])
-            declared[c] = describeControl(c);
+    for (const c of el.controls) {
+        if (!TRAIT_WRITES[c])
+            continue;
+        const base = TRAIT_WRITES[c].writes.some((w) => w.target === 'config' && isBaseOnlyConfig(type, w.writeKey));
+        declared[c] = { ...describeControl(c), ...(base ? { responsive: false } : {}) };
+    }
+    const preconditions = WRITE_PRECONDITIONS.filter((p) => p.types.includes(type)).map(({ types: _, ...p }) => p);
+    const bindable = bindableFields(type);
     return {
         type: el.type,
         hints: { useWhen: el.useWhen, avoidWhen: el.avoidWhen, contentTips: el.contentTips },
@@ -137,6 +223,15 @@ export function traitsFor(type, control) {
             groups: t.groups.map((g) => ({ group: g.label, controls: g.controls })),
         })),
         declared,
+        ...(baseOnly.length ? { base_only: baseOnly } : {}),
+        // Legal apart, meaningless together — the platform's own declaration.
+        ...(preconditions.length ? { preconditions } : {}),
+        // The click actions per trigger; binding_events replaces them once the node
+        // carries a purchase binding (add_to_cart is the BINDING, never an event).
+        ...(el.events ? { events: el.events } : {}),
+        ...(el.bindingEvents ? { binding_events: el.bindingEvents } : {}),
+        // The specials a record binding may target on this element.
+        ...(bindable.length ? { bindable } : {}),
         // The keys this element actually seeds. For `config` and `specials` —
         // which, unlike `style`, are NOT open — this is the machine-readable
         // answer to "what does this element store", and often the only one.

package/dist/catalog/formrules.generated.js

@@ -0,0 +1,29 @@
+// GENERATED by scripts/gen-catalog.ts — do not edit by hand.
+// Source: <WB_REPO>/schema/src/elements/formRules.ts (RULE_ACTIONS, RuleJoin) and
+// schema/src/elements/fieldCondition.ts (CONDITION_OPS), asserted against
+// server/internal/forms/{rules,condition}.go.
+/**
+ * The vocabulary of `specials.formRules` on a form root. A rule using a word
+ * outside these lists is DROPPED by every reader (editor, page, server) with no
+ * error, so the field it governs simply never changes.
+ */
+export const FORM_RULE_VOCAB = {
+    "joins": [
+        "and",
+        "or"
+    ],
+    "ops": [
+        "is",
+        "isNot",
+        "filled",
+        "empty",
+        "contains",
+        "notContains"
+    ],
+    "actions": [
+        "hidden",
+        "shown",
+        "optional",
+        "required"
+    ]
+};

package/dist/domains/site/findings.js

@@ -94,6 +94,21 @@ export const FIX = {
     no_h1: 'Make the page\'s main title an h1: sb_set id "<id>", namespace specials, keys ' +
         '{ "htmlTag": "h1" } — ONE per page, on the heading the page is about (the first one ' +
         'is named here; pick a different one if it is not the title). Every heading ships as h2.',
+    invalid_action: 'Re-issue it through sb_event (id "<id>", trigger "<key>"), which refuses an action the ' +
+        'element does not offer and lists the ones it does — or sb_event action "none" to drop it. ' +
+        'A purchase is a BINDING (sb_bind action "add_to_cart"), never a click action.',
+    action_missing_target: 'Give the action its target: sb_event id "<id>", action "<key>", payload ' +
+        '{ "url": "/path" } for go_to_url / open_page (open_page needs the resolved url — no ' +
+        'renderer resolves a page id), { "id": "<popup id>" } for popup.',
+    no_data_context: 'Give it a record: put it inside a list-dataset / dataset-block, pin one with sb_bind ' +
+        '(target id), or move it to a page whose type supplies "<key>" (product, category, course, ' +
+        'post, blog). Off those it renders its placeholder for ever.',
+    unread_value: 'Write a value the renderer reads: sb_traits_for "<type>" lists them; sb_set id "<id>" ' +
+        'with one, at the same breakpoint it is stored at.',
+    // ADVICE, never a blocker: the snippet works. The cost is that nobody can edit
+    // it in the inspector, it ignores the theme, and it is invisible to sb_review.
+    custom_code_native: 'Consider rebuilding it natively: sb_catalog_search "<key>" → sb_traits_for → sb_add, ' +
+        'then sb_remove id "<id>". Keep custom-code for a script or embed no element covers.',
     stuck_no_host: 'Pin something: sb_set id "<id>" (or the section it lives in), namespace style, keys ' +
         '{ "position": "sticky" } — sb_set seeds the offset and the layer order with it. Until ' +
         'then the platform compiles no rule for this state at all, so the override is stored, ' +

package/dist/domains/site/navhref.js

@@ -1,3 +1,4 @@
+import { ELEMENTS } from '../../catalog/elements.generated.js';
 /**
  * THE BRIDGE BETWEEN A CLICK ACTION AND THE THING A RENDERER ACTUALLY READS.
  *
@@ -49,8 +50,14 @@ export const PRODUCT_ACTION_BINDING_ID = 'bind-product-action';
  * a checkout hop is never a plain link, and the platform's own comment says so.
  */
 export const NAVIGATION_ACTIONS = ['go_to_url', 'open_page', 'go_to_checkout'];
-/** The two that a renderer expects to meet as an `<a href>`. */
-const PROJECTABLE = new Set(['go_to_url', 'open_page']);
+/**
+ * The actions a SOLE click projects onto `specials.href` — the platform's
+ * `projectsHref` (`schema/src/actions/engine.ts`). `scroll_to` degrades to a
+ * fragment link (`#<targetId>`), because publish stamps every node's id as
+ * its DOM id; until the catalog carries it, `sb_event` refuses it as an
+ * action no element offers, so this branch is inert rather than a guess.
+ */
+const PROJECTABLE = new Set(['go_to_url', 'open_page', 'scroll_to']);
 /**
  * The destination an event projects onto `specials.href`, or undefined.
  *
@@ -62,6 +69,10 @@ const PROJECTABLE = new Set(['go_to_url', 'open_page']);
 export function eventHref(ev) {
     if (!ev || !PROJECTABLE.has(ev.action ?? ''))
         return undefined;
+    if (ev.action === 'scroll_to') {
+        const id = (ev.payload ?? {}).targetId;
+        return typeof id === 'string' && id !== '' ? `#${id}` : undefined;
+    }
     const url = (ev.payload ?? {}).url;
     return typeof url === 'string' && url !== '' ? url : undefined;
 }
@@ -133,7 +144,9 @@ export function hrefPatches(id, events, purchaseBound, current) {
  */
 export function deadNavigation(node) {
     const sole = soleNavigationClick(node.events, hasPurchaseBinding(node.bindings));
-    if (!sole)
+    // A scroll still runs with no href — publish emits its ScrollControl call
+    // beside the fragment link — so only the no-JS fallback is missing, not the click.
+    if (!sole || sole.action === 'scroll_to')
         return null;
     const url = eventHref(sole);
     if (url === undefined)
@@ -141,3 +154,64 @@ export function deadNavigation(node) {
     const href = (node.specials ?? {}).href;
     return typeof href === 'string' && href !== '' ? null : { url };
 }
+/**
+ * The payload key each action cannot work without, read off
+ * `schema/src/actions/actions/{goToUrl,openPage,openPopup}.ts` and the Go that
+ * consumes them (`navhref.ts`'s `eventHref`, `popupTargetProps` in
+ * `render/nodes/helpers.go`). `open_page` asks for `url` rather than the `id`
+ * the platform validates, because the url is what renders.
+ */
+export const PAYLOAD_NEEDS = {
+    go_to_url: {
+        key: 'url',
+        why: 'publishes with no href and goes nowhere',
+        shape: '{ "url": "/path or https://…", "openInNewTab": false }',
+    },
+    open_page: {
+        key: 'url',
+        why: 'publishes with no href — neither renderer can resolve a page id, only a url',
+        shape: '{ "linkType": "page", "id": "<page id>", "label": "<page name>", "url": "/<page path>" }',
+    },
+    popup: {
+        key: 'id',
+        why: 'publishes a PopupControl call with no target, which opens nothing',
+        shape: '{ "id": "<the pop-up\'s overlay id, from sb_store popup>", "label": "<name>" }',
+    },
+    scroll_to: {
+        key: 'targetId',
+        why: 'publishes a ScrollControl call with no target, which scrolls nowhere',
+        shape: '{ "targetId": "<the section or block node id>", "label": "<name>" }',
+    },
+};
+/**
+ * The click-action allow-list that is LIVE for this node — the one table
+ * `sb_event` refuses by and `sb_review` reports by, so the two cannot drift.
+ *
+ * `activeEvents` in the platform (`return action ? binding_events : events`):
+ * a purchase-bound control swaps to `meta.bindingEvents`.
+ *
+ * PLUS ONE CONTEXT RULE THE META CANNOT STATE: `close_popup` inside a pop-up.
+ * The action declares the click trigger and is wired for ANY node
+ * (`islandCallForAction`, render/nodes/helpers.go — EventAttrs never consults
+ * the meta), and it resolves its panel by proximity (`closest('.wb-popup')`).
+ * No element meta lists it, yet the platform's own pop-up seed
+ * (`editor/src/features/overlays/seed.ts`) ships a button carrying it, and the
+ * editor keeps it selectable through `withCurrent`. So inside a `popup` it is
+ * live; outside one it has no panel to close.
+ */
+export function liveEventTable(nodes, id) {
+    const node = nodes[id];
+    const meta = ELEMENTS[node?.data?.type ?? ''];
+    if (!meta?.events)
+        return undefined;
+    const table = (hasPurchaseBinding(node?.bindings) && meta.bindingEvents) || meta.events;
+    if (!table.click || table.click.includes('close_popup'))
+        return table;
+    const seen = new Set();
+    for (let p = node?.data?.parent; p && !seen.has(p); p = nodes[p]?.data?.parent) {
+        seen.add(p);
+        if (nodes[p]?.data?.type === 'popup')
+            return { ...table, click: [...table.click, 'close_popup'] };
+    }
+    return table;
+}

package/dist/domains/site/readiness.js

@@ -17,8 +17,7 @@
  * that fires on a correctly built site is one the reader learns to ignore.
  */
 import { cartGalleryThumbs, cartRelocalize, cartSeedLocale } from './cartlang.js';
-/** The purchase binding an Add-to-cart / Buy-now button carries. */
-const PRODUCT_ACTION_BINDING_ID = 'bind-product-action';
+import { PRODUCT_ACTION_BINDING_ID } from './navhref.js';
 /** Element types that only make sense in a store. */
 const COMMERCE_TYPES = [
     'cart-order',

package/dist/domains/site/review.js

@@ -4,7 +4,8 @@ import { bandOf } from './traps.js';
 import { HOVER_STATE, hoverHome } from './hover.js';
 import { ELEMENTS, BINDING_SOURCES, BOUND_SPECIALS, FIRST_CHILD_ONLY, SATELLITE_RULES, ELEMENT_SEEDS } from '../../catalog/elements.generated.js';
 import { fill } from './findings.js';
-import { deadNavigation } from './navhref.js';
+import { deadNavigation, liveEventTable, PAYLOAD_NEEDS } from './navhref.js';
+import { unknownValueNote, unknownWriteNote, vocabularyFor, vocabularyForWrite } from './vocabulary.js';
 /**
  * A defect somebody looking at the page would see.
  *
@@ -34,7 +35,8 @@ export const REVIEW_NOTICE = 'FIX THESE. Each one is a defect a visitor will see
     'finding names, then review again until the list is empty. Do not report the page as done ' +
     'while findings stand; if you believe one is a false positive, say which and why. ' +
     'A finding marked overlay:true is in the cart drawer or a pop-up — fix it the same way ' +
-    '(sb_set lands there), but it is SITE-WIDE, so fix it once rather than once per page.';
+    '(sb_set lands there), but it is SITE-WIDE, so fix it once rather than once per page. ' +
+    '`advice` lists what works but is hard to edit — never a blocker.';
 /** The specials keys an element seeds that hold its visible content. */
 function contentKeys(type) {
     const seeded = ELEMENTS[type]?.defaults.specials ?? {};
@@ -126,6 +128,72 @@ const LINK_SPECIALS = new Set(['boundHref', 'boundHrefLabel', 'boundProductURL']
 function drawsItsOwnContent(type) {
     return (BOUND_SPECIALS[type] ?? []).some((k) => !LINK_SPECIALS.has(k));
 }
+/** Binding-source prefixes that name a RECORD (not `site.*`, which every page has). */
+const RECORD_ENTITIES = new Set(['product', 'category', 'course', 'article', 'blogCategory']);
+/**
+ * Which records a page TYPE supplies outside any repeater — read off the
+ * platform's own seeds (STORE_PAGE_SEEDS bind exactly these at top level).
+ */
+const PAGE_ENTITIES = {
+    product: ['product'],
+    category: ['category'],
+    course: ['course'],
+    post: ['article'],
+    blog: ['blogCategory', 'category'],
+};
+/** Does this node or an ancestor PIN a record (`bindings[0].target.id`)? */
+function pinnedAbove(d, id) {
+    for (let x = id; x && d.nodes[x]; x = d.nodes[x].data.parent) {
+        const b0 = d.nodes[x].bindings?.[0];
+        if (b0?.target?.id)
+            return true;
+    }
+    return false;
+}
+/**
+ * The native element a custom-code snippet re-implements, or null.
+ *
+ * Judged on the MARKUP left once every <script>, <style> and comment is
+ * stripped — so an analytics tag, a chat widget's mount div, or HTML built
+ * inside a script is never flagged — and only when that markup outweighs the
+ * script (mostly markup). An iframe counts only for the three hosts a native
+ * embed exists for; any other iframe is a third-party embed and stays.
+ * ponytail: tag-presence heuristic, not a parser — tighten if it cries wolf.
+ */
+function nativeFor(code) {
+    const scripts = code.match(/<script\b[\s\S]*?(<\/script>|$)/gi) ?? [];
+    const markup = code
+        .replace(/<script\b[\s\S]*?(<\/script>|$)/gi, '')
+        .replace(/<style\b[\s\S]*?(<\/style>|$)/gi, '')
+        .replace(/<!--[\s\S]*?-->/g, '');
+    if (markup.trim().length < scripts.join('').length)
+        return null;
+    // A form POSTING TO ANOTHER HOST (a Mailchimp / Klaviyo embed) is a
+    // third-party integration, not hand-built markup: a native form submits to
+    // this platform only, so there is nothing native to swap it for.
+    if (/<form\b[^>]*\baction\s*=\s*["']?(https?:)?\/\//i.test(markup))
+        return null;
+    const iframe = /<iframe\b[^>]*\bsrc\s*=\s*["']?([^"'\s>]+)/i.exec(markup)?.[1] ?? '';
+    if (/youtube(-nocookie)?\.com|youtu\.be/i.test(iframe))
+        return 'youtube';
+    if (/vimeo\.com/i.test(iframe))
+        return 'vimeo';
+    if (/google\.[a-z.]+\/maps|maps\.google\./i.test(iframe))
+        return 'google-map';
+    if (/<form\b/i.test(markup))
+        return 'form';
+    if (/<(nav|ul|ol)\b/i.test(markup) && (markup.match(/<a\b/gi) ?? []).length >= 2)
+        return 'menu';
+    if (/<h[1-6]\b/i.test(markup))
+        return 'heading';
+    if (/<video\b/i.test(markup))
+        return 'video';
+    if (/<img\b/i.test(markup))
+        return 'image';
+    if (/<button\b/i.test(markup))
+        return 'button';
+    return null;
+}
 /**
  * Everything wrong with this page that a person would notice.
  *
@@ -322,6 +390,113 @@ opts = {}) {
                 ...(inOverlay.has(id) ? { overlay: true } : {}),
             });
         }
+        // AN EVENT THE ELEMENT CANNOT FIRE, OR ONE WITH NOWHERE TO GO. `sb_event`
+        // refuses both at write time; a document gets here by other roads (an
+        // import, a template, a hand-built sb_api_call). Same table setEvent reads
+        // (`liveEventTable` in tools/live.ts): bindingEvents once a purchase binds.
+        const events = n.events ?? [];
+        if (events.length) {
+            const table = liveEventTable(d.nodes, id);
+            for (const ev of events) {
+                const trigger = String(ev?.name ?? '');
+                const action = String(ev?.action ?? '');
+                if (!table?.[trigger]?.includes(action)) {
+                    out.push({
+                        code: 'invalid_action',
+                        nodeId: id,
+                        type,
+                        problem: `"${action}" on ${trigger || '(no trigger)'} is not an action a ${type} offers` +
+                            (table?.[trigger] ? ` there (${table[trigger].join(', ')})` : '') +
+                            ' — it is stored and never fires.',
+                        key: trigger,
+                        fix: fill('invalid_action', { id, key: trigger }),
+                    });
+                    continue;
+                }
+                // The same table `sb_event` refuses by — one list, so the two cannot drift.
+                const need = PAYLOAD_NEEDS[action]?.key;
+                const v = (ev.payload ?? {})[need ?? ''];
+                if (need && (typeof v !== 'string' || v.trim() === '')) {
+                    out.push({
+                        code: 'action_missing_target',
+                        nodeId: id,
+                        type,
+                        problem: `Its ${trigger} "${action}" carries no payload.${need}, so the click does nothing.`,
+                        key: action,
+                        fix: fill('action_missing_target', { id, key: action }),
+                    });
+                }
+            }
+        }
+        // A RECORD-BOUND ELEMENT WITH NO RECORD. Inside a repeater the row supplies
+        // one; on an entity page (product, category, post…) the page does; a pin
+        // (`bindings[0].target.id`, render/html.go pinnedEntityID) does for its
+        // subtree. Anywhere else the binding resolves to nothing and the element
+        // renders its seeded placeholder for ever — saved, published, no warning.
+        // Overlays are skipped: one drawer serves every page type.
+        if (opts.pageType !== undefined && !inRepeater.get(id) && !inOverlay.has(id)) {
+            const entities = PAGE_ENTITIES[opts.pageType] ?? [];
+            const missing = (n.bindings ?? [])
+                .map((b) => String(b?.source ?? '').split('.')[0])
+                .find((e) => RECORD_ENTITIES.has(e) && !entities.includes(e));
+            if (missing && !pinnedAbove(d, id)) {
+                out.push({
+                    code: 'no_data_context',
+                    nodeId: id,
+                    type,
+                    problem: `Bound to a ${missing} record, but it sits in no repeater and a "${opts.pageType}" ` +
+                        'page supplies none — it renders its placeholder on the published page.',
+                    key: missing,
+                    fix: fill('no_data_context', { id, key: missing }),
+                });
+            }
+        }
+        // A STORED VALUE NO RENDERER READS. The same vocabulary `sb_set` warns from
+        // (`unknownWriteNote` / `unknownValueNote`), asked of what the document
+        // already holds — base and every breakpoint — because an import or a write
+        // made before the warning existed is still publishing the fallback.
+        {
+            const layered = n;
+            const layers = [
+                ['config', layered.config],
+                ['specials', n.specials],
+                ...Object.values(layered.responsive ?? {}).flatMap((r) => [['config', r?.config], ['specials', r?.specials]]),
+            ];
+            const said = new Set();
+            for (const [ns, slot] of layers) {
+                for (const [k, v] of Object.entries(slot ?? {})) {
+                    const unread = unknownWriteNote(type, ns, k, v) ?? (ns === 'config' ? unknownValueNote(k, v) : null);
+                    if (!unread || said.has(`${ns}.${k}=${String(v)}`))
+                        continue;
+                    said.add(`${ns}.${k}=${String(v)}`);
+                    const legal = (vocabularyForWrite(type, ns, k) ?? (ns === 'config' ? vocabularyFor(k) : null))?.values ?? [];
+                    out.push({
+                        code: 'unread_value',
+                        nodeId: id,
+                        type,
+                        problem: `${ns}.${k} = ${JSON.stringify(v)} is not a value the renderer reads; it publishes ` +
+                            `as its fallback with no error. Legal: ${legal.map((x) => x || '""').join(', ')}.`,
+                        key: `${ns}.${k}`,
+                        fix: fill('unread_value', { id, type }),
+                    });
+                }
+            }
+        }
+        if (type === 'custom-code') {
+            const native = nativeFor(String((n.specials ?? {}).code ?? ''));
+            if (native) {
+                out.push({
+                    code: 'custom_code_native',
+                    nodeId: id,
+                    type,
+                    severity: 'maintenance',
+                    problem: `Hand-written markup a native ${native} covers. It works, but no inspector can edit ` +
+                        'it, it ignores the theme, and sb_review cannot see inside it.',
+                    key: native,
+                    fix: fill('custom_code_native', { id, key: native }),
+                });
+            }
+        }
         // PINNING FAILS WITH NOTHING ON SCREEN AND NOTHING IN THE LOG — both halves
         // of it — which is exactly what a review is for. `sb_set` refuses the second
         // case at write time, but a document reaches here by other roads: an import,