sbuilder-mcp 0.76.3 → 0.77.0

package/CHANGELOG.md

@@ -6,6 +6,29 @@ 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
+- `sb_look` reports two new layout findings, `title_bar_stranded` and `title_bar_offcenter`, when a hand-built heading-plus-action row leaves the button short of the right edge or off the heading's centre line, and skips rows that declare a centred layout.
+
+### Fixed
+- `sb_import` and `sb_import_site` now map a heading beside a single action such as "Xem tất cả" to a space-between row with centred alignment, so the button sits on the right edge, shares the heading's centre line, and stacks left-aligned on mobile.
+
 ## [0.76.3] - 2026-09-28
 
 ### Fixed

package/CHANGELOG.vi.md

@@ -6,6 +6,29 @@ 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
+- `sb_look` báo thêm hai finding bố cục `title_bar_stranded` và `title_bar_offcenter` khi một hàng tiêu đề kèm nút được dựng tay để nút lệch khỏi mép phải hoặc lệch tâm dọc so với tiêu đề, và bỏ qua các hàng khai báo bố cục căn giữa.
+
+### Fixed
+- `sb_import` và `sb_import_site` giờ ánh xạ một tiêu đề đi kèm một nút duy nhất như "Xem tất cả" thành hàng space-between căn giữa theo chiều dọc, nên nút nằm sát mép phải, cùng tâm dọc với tiêu đề và xếp dọc căn trái trên mobile.
+
 ## [0.76.3] - 2026-09-28
 
 ### Fixed

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

@@ -71,6 +71,11 @@ export const FIX = {
     dead_binding_field: 'Rebind with sb_bind and a field of the form "specials.<key>".',
     off_canvas: 'Give it a width that can shrink — sb_set id "<id>", namespace style, keys { "maxWidth": "100%" } at this breakpoint.',
     text_too_small: 'Raise it for this breakpoint: sb_set id "<id>", namespace style, keys { "fontSize": "16px" }.',
+    title_bar_stranded: 'Put the action on the right edge: sb_set id "<id>", namespace style, keys ' +
+        '{ "justifyContent": "space-between", "alignItems": "center" }, and sb_set id "<cell>", ' +
+        'namespace style, keys { "flex": "0 0 auto", "width": "auto" }. On mobile give "<id>" ' +
+        '{ "flexDirection": "column", "alignItems": "flex-start" }.',
+    title_bar_offcenter: 'Centre the pair on one line: sb_set id "<id>", namespace style, keys { "alignItems": "center" } at this breakpoint.',
     overlap: 'Check the two for a fixed height or a negative margin at this breakpoint; sb_look with node_id on each shows which one is out of place.',
     // Both sticky findings name a node OTHER than the one at fault, because in
     // both cases the node carrying the defect is not the node to edit.
@@ -89,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/importmap.js

@@ -184,6 +184,22 @@ function textScale(slug, fallback) {
     }
     return { style, config: { textGlobalStyle: slug } };
 }
+const holds = (c, kind) => c.kind === kind || (c.children ?? []).some((k) => holds(k, kind));
+/** A button, or a packed run of nothing but buttons. */
+const isAction = (c) => c.kind === 'button' || (c.kind === 'group' && !!c.children?.length && c.children.every((k) => k.kind === 'button'));
+/**
+ * A row of a heading block and ONE action — a shelf's title and its "see all".
+ * `align: 'center'` is a caller asking for a centred band, and keeps the
+ * equal-share answer it asked for.
+ */
+export function isTitleBar(c) {
+    const kids = c.children ?? [];
+    if (c.kind !== 'group' || c.direction === 'column' || c.wrap || c.pack || c.align === 'center')
+        return false;
+    if (kids.length !== 2)
+        return false;
+    return holds(kids[0], 'heading') && !holds(kids[0], 'button') && isAction(kids[1]);
+}
 function one(c, t) {
     const n = shape(c, t);
     const x = c.extra;
@@ -510,6 +526,43 @@ function shape(c, t) {
                     })),
                 };
             }
+            // A TITLE BAR IS NOT TWO EQUAL COLUMNS. A heading with one action beside
+            // it ("Xem tất cả") went down the equal-share path below: each side got
+            // half the row, the action sat at the LEFT of its half — the middle of
+            // the band — and `flex-start` hung it from the heading's top edge. The
+            // shape wanted is the opposite on both axes: the heading takes what it
+            // needs, the action sits on the right edge, and both share a centre line.
+            // A phone stacks them and keeps them flush left.
+            if (kids.length === 2 && isTitleBar(c)) {
+                return {
+                    type: 'flex-block',
+                    style: {
+                        width: '100%',
+                        display: 'flex',
+                        flexDirection: 'row',
+                        flexWrap: 'nowrap',
+                        justifyContent: 'space-between',
+                        alignItems: 'center',
+                        gap: '24px',
+                    },
+                    responsive: { mobile: { style: { flexDirection: 'column', alignItems: 'flex-start', gap: '12px' } } },
+                    // `width: auto` on both, for the reason the packed row records:
+                    // `flex-block` seeds `width: 100%`, which would hand the heading the
+                    // whole line and push the action onto nothing.
+                    children: [
+                        {
+                            type: 'flex-block',
+                            style: { flex: '1 1 auto', width: 'auto', minWidth: '0', display: 'flex', flexDirection: 'column', gap: '8px' },
+                            children: [kids[0]],
+                        },
+                        {
+                            type: 'flex-block',
+                            style: { flex: '0 0 auto', width: 'auto', display: 'flex', flexDirection: 'column' },
+                            children: [kids[1]],
+                        },
+                    ],
+                };
+            }
             if (c.wrap) {
                 return {
                     type: 'flex-block',

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',