sbuilder-mcp 0.62.0 → 0.63.1

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.63.1] - 2026-09-24
+
+### Fixed
+- Live-edit frames now carry the open page's id from the moment a room is joined and whenever a new page is opened afterward, so the editor's own per-page filter no longer drops every ops, cursor, and select frame this server sends.
+- A second `sb_live_join`, or opening a page on a different site while already in a room, now leaves the previous room instead of leaving its socket connected and reconnecting for the rest of the process.
+- Opening a page on a site other than the one the current live room belongs to now leaves that room first, so a failed join can no longer strand the session in the wrong site's room.
+- The server process now exits when the MCP client closes stdin, instead of being kept alive indefinitely by the live-room socket and its reconnect timer.
+
+## [0.63.0] - 2026-09-21
+
+### Added
+- `sb_store` gained `global_attach` and `global_detach` actions to put an existing shared header or footer onto the open page, or take one off, without hand-writing the composed stamp.
+- `sb_page_state` is a new tool that reports whether the editor's draft, the published page, and this session's own copy of a page agree, and lists the real recovery points (autosave checkpoints and labelled versions) when they do not.
+- `sb_publish` now reports the published revision's `id`, `publishedAt`, and the draft version it was compiled from, and takes a `verify` argument that fetches the live storefront and confirms the origin is actually serving that revision.
+
+### Fixed
+- `sb_event` now writes the `<a href>` a renderer actually reads alongside a navigation click, since `node.events` is never read for a sole `go_to_url`/`open_page` click; every navigation authored before this fix rendered, saved, and published a control that did nothing when a shopper clicked it.
+- `sb_review` no longer throws on a page whose document names a child node it does not hold; it reports the defect as `missing_node` instead.
+- `sb_review` reports `dead_nav` for a navigation click that reached the document without its href projection.
+- `sb_look`'s overlap check and its `node_id` framing now recognize an overlay (such as the cart drawer) by how it actually renders off-screen, not only by its composition stamp, removing dozens of false off-canvas findings per page and letting a drawer authored straight into a page document be framed at all.
+- API errors thrown by a tool now carry the platform's own error `code` and HTTP status in the message, so a failure like a band-order refusal can be matched against its documented code instead of only its prose.
+- `sb_store`'s `chrome` action and `sb_page_create` now re-read and re-store the page immediately after attaching a global section, so the platform's usage count and referencing-pages list reflect the attachment right away instead of only after a later save.
+
 ## [0.62.0] - 2026-09-20
 
 ### Added

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.63.1] - 2026-09-24
+
+### Fixed
+- Các frame live-edit giờ mang theo id của trang đang mở ngay từ lúc vào phòng và mỗi khi một trang mới được mở sau đó, để bộ lọc theo từng trang của chính editor không còn loại bỏ mọi frame ops, cursor và select mà server này gửi đi.
+- Gọi `sb_live_join` lần thứ hai, hoặc mở một trang thuộc site khác trong khi đang ở trong một phòng, giờ sẽ rời phòng cũ thay vì để socket của nó tiếp tục kết nối và tự reconnect trong suốt phần đời còn lại của tiến trình.
+- Mở một trang thuộc site khác với site của phòng live hiện tại giờ sẽ rời phòng đó trước, để một lần join thất bại không còn có thể khiến session bị mắc kẹt trong phòng của site sai.
+- Tiến trình server giờ thoát khi client MCP đóng stdin, thay vì bị giữ sống vô thời hạn bởi socket của phòng live và timer reconnect của nó.
+
+## [0.63.0] - 2026-09-21
+
+### Added
+- `sb_store` có thêm hai action `global_attach` và `global_detach` để đặt một header hoặc footer dùng chung đã tồn tại lên trang đang mở, hoặc gỡ nó ra, mà không cần tự tay viết stamp đã compose.
+- `sb_page_state` là một tool mới, báo cáo xem bản draft của editor, trang đã publish, và bản sao của session này có khớp nhau hay không, đồng thời liệt kê các điểm khôi phục thật sự (checkpoint autosave và version có nhãn) khi chúng không khớp.
+- `sb_publish` giờ báo cáo `id` của bản ghi đã publish, `publishedAt`, và version draft mà nó được biên dịch từ đó, đồng thời nhận tham số `verify` để lấy trang storefront trực tiếp và xác nhận origin có đang phục vụ đúng bản đó không.
+
+### Fixed
+- `sb_event` giờ ghi `<a href>` mà renderer thực sự đọc cùng lúc với một click điều hướng, vì `node.events` không bao giờ được đọc cho một click `go_to_url`/`open_page` đơn lẻ; mọi điều hướng được tạo trước bản sửa này render, lưu và publish thành một control không làm gì khi khách bấm vào.
+- `sb_review` không còn ném lỗi khi tài liệu của trang trỏ tới một node con mà nó không có; giờ báo cáo lỗi này dưới dạng `missing_node`.
+- `sb_review` báo cáo `dead_nav` cho một click điều hướng đến được tài liệu mà không có phép chiếu href của nó.
+- Kiểm tra chồng lấp của `sb_look` và việc khung hình theo `node_id` giờ nhận diện một overlay (như cart drawer) dựa trên cách nó thực sự render ngoài màn hình, chứ không chỉ dựa vào stamp compose, loại bỏ hàng chục phát hiện off-canvas giả trên mỗi trang và cho phép khung hình một drawer được tạo thẳng vào tài liệu trang.
+- Lỗi API do một tool ném ra giờ mang theo `code` lỗi và mã trạng thái HTTP của nền tảng trong message, để một lỗi như bị từ chối do sai thứ tự band có thể được đối chiếu với mã đã tài liệu hóa thay vì chỉ dựa vào câu chữ.
+- Action `chrome` của `sb_store` và `sb_page_create` giờ đọc lại và lưu lại trang ngay sau khi gắn một global section, để số lượt sử dụng và danh sách trang tham chiếu của nền tảng phản ánh việc gắn kết ngay lập tức thay vì chỉ sau một lần lưu sau đó.
+
 ## [0.62.0] - 2026-09-20
 
 ### Added

package/README.md

@@ -98,7 +98,8 @@ in this client: one would put the very key the platform exists to hold back into
 | `sb_template_use` | Instantiate a template into a page |
 | `sb_page_list` | Every page on the site |
 | `sb_page_create` | Create a page — a store type arrives with the editor's own starting document; `type` is the route for checkout, product, category, post, course |
-| `sb_publish` | Compile the draft into the live page (cascades to shared globals) |
+| `sb_publish` | Compile the draft into the live page (cascades to shared globals), report which revision went live, and with `verify` check the origin is serving it |
+| `sb_page_state` | Which of a page's three copies is which — the DRAFT the editor canvas shows, the PUBLISHED row the storefront serves, and this session's — plus whether the editor will render the canvas BLANK, and where the recovery points are |
 | `sb_review` | Every defect a visitor would see, each with its fix, plus the five gaps between this store and a paid order |
 | `sb_media_list` | The site's media library |
 | `sb_media_upload` | Add an image and get its URL — a local path, a URL the platform fetches, or a SEARCH for real photographs you read and pick from, one or several at a time |
@@ -109,7 +110,7 @@ in this client: one would put the very key the platform exists to hold back into
 | `sb_import` | Read a page from any public URL and add its structure and content to the open page as real elements, styled with THIS page's own tokens — a translation, not a clone |
 | `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 |
-| `sb_store` | Run a store flow that must happen in a fixed order — `checkout` (the four writes that make a working one), `form` (any of the platform's 17 templates with its own field document), `chrome` (one shared header or footer), `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) and `app` (a built-in app plus the pages it needs) |
+| `sb_store` | Run a store flow that must happen in a fixed order — `checkout` (the four writes that make a working one), `form` (any of the platform's 17 templates with its own field document), `chrome` (one shared header or footer), `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) 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 |
 
 Twenty-eight tools, **560 API operations** (193 of the 251 writes carrying a body shape read

package/README.vi.md

@@ -95,7 +95,8 @@ nhét ngược lại vào mọi bản cài.
 | `sb_template_use` | Thả một template vào trang |
 | `sb_page_list` | Mọi trang của site |
 | `sb_page_create` | Tạo một trang — trang cửa hàng sinh ra đã có sẵn tài liệu như trong editor; `type` là đường đi cho checkout, product, category, post, course |
-| `sb_publish` | Biên dịch bản nháp thành trang live (lan sang global dùng chung) |
+| `sb_publish` | Biên dịch bản nháp thành trang live (lan sang global dùng chung), báo bản nào đã lên live, và với `verify` kiểm origin đã phục vụ đúng bản đó chưa |
+| `sb_page_state` | Ba bản sao của một trang, bản nào là bản nào — bản NHÁP canvas editor hiển thị, dòng PUBLISHED storefront phục vụ, và bản phiên này giữ — kèm dự báo editor có render canvas TRẮNG không, và các điểm phục hồi nằm ở đâu |
 | `sb_review` | Mọi khiếm khuyết người xem sẽ thấy, kèm lệnh sửa từng cái, và năm khoảng trống chắn giữa cửa hàng với một đơn đã thanh toán |
 | `sb_media_list` | Thư viện ảnh của site |
 | `sb_media_upload` | Thêm ảnh và lấy URL — file trên máy, một URL để nền tảng tự tải, hoặc TÌM ảnh chụp thật để đọc mô tả rồi chọn, một hoặc nhiều tấm một lượt |
@@ -106,7 +107,7 @@ nhét ngược lại vào mọi bản cài.
 | `sb_import` | Đọc một trang từ URL công khai bất kỳ và thêm cấu trúc + nội dung của nó vào trang đang mở dưới dạng element thật, mang token của CHÍNH trang này — là dịch lại, không phải sao chép |
 | `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 |
-| `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), `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), `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ở) và `app` (một app dựng sẵn kèm những trang nó cần) |
+| `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), `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), `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ở) `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 |
 
 Hai mươi tám tool, **560 operation API** (193 trong 251 lệnh ghi có hình dạng body đọc thẳng

package/dist/domains/site/findings.js

@@ -46,6 +46,20 @@ export const FIX = {
         '"menu-item" per link, and delete the buttons with sb_remove. Add a "menu-drawer" (with a ' +
         '"hamburger-menu" trigger) for the phone, and "menu-dropdown" where a link has a sub-level. ' +
         'sb_traits_for "menu" has the controls.',
+    // The child is NAMED, because "a child is missing" without which one sends
+    // the reader back to diff two documents by hand.
+    missing_node: 'Take the dead reference out: sb_remove id "<child>" clears it when the node is merely ' +
+        'orphaned. If the content is wanted, sb_add it under "<id>" instead. Until one or the ' +
+        'other happens the platform refuses every save of this page, and a refused save is ' +
+        'reported against whatever command came next rather than this one.',
+    // THE FIX IS NOT "SET href INSTEAD OF THE EVENT" — it is to re-issue the event
+    // through the tool that now projects both. Telling a caller to write the href
+    // by hand would leave the two able to disagree again on the next edit, which
+    // is the whole defect.
+    dead_nav: 'Re-issue the click through sb_event, which now writes specials.href alongside it: ' +
+        'sb_event id "<id>", action "go_to_url", payload { "url": "<url>" }. A sole navigation ' +
+        'click renders as an <a href> and from nothing else — the renderer emits no on:click ' +
+        'for one — so the event without the href is a control that publishes and does nothing.',
     dead_menu_link: 'Write the entries the renderer actually reads: sb_set id "<id>", namespace specials, keys ' +
         '{ "menuItems": [{ "id": "mi-1", "label": "Shop", "href": "/shop" }] }. Setting menuId alone ' +
         'publishes an empty nav — the Go renderer never reads it.',

package/dist/domains/site/liveproof.js

@@ -0,0 +1,91 @@
+/**
+ * DID THE LIVE PAGE ACTUALLY START SERVING WHAT WAS JUST PUBLISHED?
+ *
+ * A publish that answers 200 proves the platform STORED a new published row.
+ * It does not prove a visitor is being served it, and the two come apart for a
+ * measured, ordinary reason: the storefront answers
+ *
+ *     cache-control: public, max-age=60
+ *
+ * so a browser — and anything in front of it — may go on showing the previous
+ * page for up to a minute. A caller who publishes, reloads, sees the old page
+ * and concludes the publish failed then "fixes" something that was never
+ * broken; a caller who publishes, does not reload, and reports the page live is
+ * making a claim nothing checked.
+ *
+ * So this fetches the page and asks a question the HTML can answer: does the
+ * markup a visitor is being served contain the node ids this publish put in it?
+ * Every element the renderer draws carries `id="<node id>"`, so the top-level
+ * band ids are a fingerprint of the document without needing to diff bytes —
+ * and the diff would be the wrong tool anyway, since the served page is
+ * assembled with a head, a runtime bundle and stylesheet links the published
+ * `html` field does not carry.
+ *
+ * CACHE-BUSTED, because the question is about the ORIGIN and not about what
+ * some intermediary happens to be holding: an unmatched query parameter makes
+ * a distinct cache key, and `Cache-Control: no-cache` asks the chain to
+ * revalidate. What comes back is therefore what the origin serves NOW, and the
+ * `max_age` reported beside it is how long somebody else's copy may differ.
+ */
+/** The node ids that are a page's top-level bands — its cheapest fingerprint. */
+export function bandIds(document) {
+    const d = document;
+    const root = d?.root_node_id;
+    if (!root || !d?.nodes)
+        return [];
+    return (d.nodes[root]?.data?.nodes ?? []).filter((id) => typeof id === 'string');
+}
+/** `max-age=<n>` out of a Cache-Control header, when it says one. */
+export function maxAgeOf(header) {
+    const m = /max-age=(\d+)/i.exec(header ?? '');
+    return m ? Number(m[1]) : undefined;
+}
+export async function proveLive(url, ids, fetchImpl = fetch) {
+    // A DISTINCT CACHE KEY. `_sb` rather than a bare `t`: the storefront's own
+    // preview route reads `t`, and colliding with a parameter the platform
+    // already means something by is how a cache-buster becomes a bug report.
+    const bust = new URL(url);
+    bust.searchParams.set('_sb', String(Date.now()));
+    let res;
+    try {
+        res = await fetchImpl(bust.toString(), { headers: { 'Cache-Control': 'no-cache' } });
+    }
+    catch (e) {
+        return {
+            url,
+            status: 0,
+            serving: false,
+            checked: ids.length,
+            note: `The live page could not be reached (${e.message}). The publish itself ` +
+                'succeeded — this check did not run, which is not the same as the page being wrong.',
+        };
+    }
+    const html = await res.text();
+    const missing = ids.filter((id) => !html.includes(`id="${id}"`));
+    const maxAge = maxAgeOf(res.headers.get('cache-control'));
+    const etag = res.headers.get('etag') ?? undefined;
+    return {
+        url,
+        status: res.status,
+        serving: res.ok && missing.length === 0,
+        checked: ids.length,
+        ...(missing.length ? { missing } : {}),
+        ...(maxAge !== undefined ? { max_age: maxAge } : {}),
+        ...(etag ? { etag } : {}),
+        ...(res.ok && missing.length === 0 && maxAge
+            ? {
+                note: `The origin is serving this revision. Another viewer's browser may hold the ` +
+                    `previous page for up to ${maxAge}s (cache-control: max-age=${maxAge}) — that is ` +
+                    'the platform\'s own caching, not a failed publish, and a hard reload ends it.',
+            }
+            : {}),
+        ...(res.ok && missing.length > 0
+            ? {
+                note: 'The page answered, and the markup does not carry every band this publish put in ' +
+                    'it. Either something in front of the origin is still serving the previous copy, ' +
+                    'or the page being served is built from a different document — re-run this check ' +
+                    'once before treating it as the second.',
+            }
+            : {}),
+    };
+}

package/dist/domains/site/navhref.js

@@ -0,0 +1,143 @@
+/**
+ * THE BRIDGE BETWEEN A CLICK ACTION AND THE THING A RENDERER ACTUALLY READS.
+ *
+ * `node.events` IS NEVER READ BY A RENDERER. The platform says so in as many
+ * words (`editor/src/stores/node.ts`, on `projectHref`) and the Go side proves
+ * it: `nodes.EventAttrs` SKIPS a sole navigation click outright —
+ *
+ *     if ev.Name == "click" && clicks == 1 && purchaseItem == "" &&
+ *         (ev.Action == "go_to_url" || ev.Action == "open_page") {
+ *         continue // the <a href> form; see above
+ *     }
+ *
+ * — on the stated assumption that the node's `specials.href` has already made
+ * it an `<a href>`, because "a call beside an anchor would navigate twice".
+ * The editor holds up that assumption by writing the event AND its href in one
+ * undo step (`projectHref`). THIS SERVER DID NOT, for as long as `sb_event`
+ * has existed.
+ *
+ * So `sb_event action:"go_to_url"` produced a node with no `href` and no
+ * `on:click`: a dead control that renders perfectly, saves, publishes, and does
+ * nothing when a shopper clicks it. Silent at every step — `sb_review` reads
+ * the tree and the tree is correct, `sb_look` photographs the page and the page
+ * looks right.
+ *
+ * MEASURED ON A LIVE STOREFRONT, which is how it was found rather than an
+ * argument for how it could happen. Three images on one home page carried
+ * `click: go_to_url {"url":"/bo-suu-tap"}` with no href, and the published
+ * markup for each was a bare `<img>` — no anchor, no `on:click` — beside a
+ * button that carried the href and rendered `<a href="/bo-suu-tap">`.
+ *
+ * Pure, and in its own module, because two callers need it for opposite
+ * reasons: `setEvent` must WRITE the projection, and `sb_review` must REPORT a
+ * document that reached here by another road (an import, a hand-built
+ * `sb_api_call`, a page authored before this fix).
+ */
+/**
+ * The RESERVED id of the purchase binding
+ * (`schema/src/elements/datasetBindings.ts:852`).
+ *
+ * It lives here rather than beside `sb_bind` because both sides of this
+ * projection need it and a copy in each is how the two drift: the renderer's
+ * `purchaseItem` is what decides whether a navigation may be an anchor at all.
+ */
+export const PRODUCT_ACTION_BINDING_ID = 'bind-product-action';
+/**
+ * Actions that leave the page (`schema/src/actions/engine.ts`).
+ *
+ * `go_to_checkout` is one of them and is deliberately NOT projectable below —
+ * 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 destination an event projects onto `specials.href`, or undefined.
+ *
+ * `open_page` reads a `url` the editor's page picker RESOLVED AND CACHED at
+ * pick time — neither renderer can resolve a page id — so an `open_page`
+ * payload carrying only an id projects nothing, exactly as the editor's own
+ * `eventHref` does.
+ */
+export function eventHref(ev) {
+    if (!ev || !PROJECTABLE.has(ev.action ?? ''))
+        return undefined;
+    const url = (ev.payload ?? {}).url;
+    return typeof url === 'string' && url !== '' ? url : undefined;
+}
+/** The `target` an event projects. Only `go_to_url` offers the choice. */
+export function eventTarget(ev) {
+    if (!ev || ev.action !== 'go_to_url')
+        return undefined;
+    return (ev.payload ?? {}).openInNewTab === true ? '_blank' : undefined;
+}
+/** Does this node carry the reserved purchase binding? */
+export function hasPurchaseBinding(bindings) {
+    return (bindings ?? []).some((b) => b?.id === PRODUCT_ACTION_BINDING_ID);
+}
+/**
+ * The click event this node's `<a href>` projection comes from, or null.
+ *
+ * EXACTLY the editor's rule, and each clause earns its place:
+ *  - exactly ONE click event — the moment anything else joins the list the
+ *    renderer emits every one of them as a `Nav#go` call in the chain, and an
+ *    href beside that chain would navigate twice;
+ *  - a PROJECTABLE navigation action, so `go_to_checkout` keeps its runtime
+ *    call;
+ *  - no purchase binding — a bound button's navigation always rides chained
+ *    after `AddToCart#add`, never as a link.
+ */
+export function soleNavigationClick(events, purchaseBound) {
+    if (purchaseBound)
+        return null;
+    const clicks = (events ?? []).filter((e) => e?.name === 'click');
+    if (clicks.length !== 1)
+        return null;
+    return PROJECTABLE.has(clicks[0].action ?? '') ? clicks[0] : null;
+}
+/**
+ * The patches that put `specials.href`/`specials.target` back in step with a
+ * node's click list.
+ *
+ * `undefined` becomes an `unset`, and a key that is already absent produces NO
+ * patch at all — both mirroring the editor's `PatchRecorder.set`, because these
+ * go on the wire to peers running that code and an empty write would churn a
+ * revision for nothing.
+ */
+export function hrefPatches(id, events, purchaseBound, current) {
+    const sole = soleNavigationClick(events, purchaseBound);
+    const want = {
+        href: eventHref(sole),
+        target: eventTarget(sole),
+    };
+    const out = [];
+    for (const [key, value] of Object.entries(want)) {
+        const had = (current ?? {})[key];
+        if (value === undefined) {
+            if (had !== undefined)
+                out.push({ op: 'unset', path: ['nodes', id, 'specials', key] });
+            continue;
+        }
+        if (had !== value)
+            out.push({ op: 'set', path: ['nodes', id, 'specials', key], value });
+    }
+    return out;
+}
+/**
+ * Would this node's navigation reach the shopper?
+ *
+ * The question `sb_review` asks, and the one no screenshot answers: a dead
+ * navigation control is the RIGHT PIXELS with nothing behind them. Returns the
+ * destination the author meant when the answer is no, so the finding can name
+ * the page the click was supposed to reach.
+ */
+export function deadNavigation(node) {
+    const sole = soleNavigationClick(node.events, hasPurchaseBinding(node.bindings));
+    if (!sole)
+        return null;
+    const url = eventHref(sole);
+    if (url === undefined)
+        return null;
+    const href = (node.specials ?? {}).href;
+    return typeof href === 'string' && href !== '' ? null : { url };
+}

package/dist/domains/site/offscreen.js

@@ -0,0 +1,103 @@
+import { childrenOf, isOverlay, subtreeIds } from '../../core/tree.js';
+/**
+ * PARKED OFF-SCREEN UNTIL A SHOPPER OPENS IT — a fact about the ELEMENT'S
+ * RENDERER, not about how the node reached the page.
+ *
+ * `measure` already skipped overlays, and the skip was built from `isOverlay`,
+ * which asks a COMPOSITION question: does this node carry `specials.overlayId`
+ * and sit directly under ROOT. That is the right question for trap 1 — an
+ * overlay is composed onto ROOT on read and stripped on write, so a write must
+ * refuse its root — and it is the WRONG question here, because being off-screen
+ * is something the element's own CSS does:
+ *
+ *     .wb-cart-drawer        { visibility: hidden; transform: translateX(105%) }
+ *     .wb-cart-drawer.is-open{ visibility: visible; transform: none }
+ *
+ * A `cart-drawer` authored straight into a page document — no `overlayId`, just
+ * a node somebody added — parks itself exactly the same way. MEASURED on a live
+ * storefront: every page carried an unstamped `cart-drawer` as a ROOT child, so
+ * the skip set came out EMPTY and `sb_look` reported THIRTEEN off-canvas
+ * findings per page, at every width, on pages that were completely correct.
+ * "A list that is two dozen false positives long is a list nobody reads" is the
+ * comment on the skip this repairs.
+ *
+ * The same blind spot has a second symptom, which is why this is one module and
+ * not a patch in `measure`: `sb_look` opens an overlay before framing a node
+ * inside it, and it decides what to open with `overlayRoot` — the same
+ * stamp-based test. Framing the quantity stepper inside an unstamped drawer
+ * therefore did not open it, the clip landed outside the image, and Playwright
+ * answered "Clipped area is either empty or outside the resulting image",
+ * naming neither the overlay nor the reason.
+ *
+ * THIS IS THE `Box.position` LESSON AGAIN, one field along: a comment described
+ * behaviour the code did not have, because the code asked a question adjacent
+ * to the one the comment was about.
+ *
+ * HAND-KEPT, and the replacement is nameable. The honest source is the Go CSS —
+ * an element whose `render/nodes/<type>/css.go` hides itself until `.is-open` —
+ * which is mechanically readable and is what a codegen reader should take. It
+ * is four types today, and the element metas carry nothing that separates them:
+ * all of `cart-drawer`, `popup`, `menu-drawer`, `menu-panel` and `hamburger-menu`
+ * report `category: "basic"`, so there is nothing in the catalog to derive this
+ * from. Until that reader exists, a new overlay element the platform ships is a
+ * silent gap here — the same standing debt `INERT_ON_ADD` carries, recorded
+ * rather than hidden.
+ */
+export const OFFSCREEN_UNTIL_OPEN = new Set([
+    // Both measured directly in the Go: these two translate themselves out of the
+    // viewport and back on `.is-open`.
+    'cart-drawer',
+    'hamburger-menu',
+    // These two are hidden rather than translated, so they do not usually measure
+    // as off-canvas — but they are the same KIND of thing, they are what
+    // `sb_look` must open before framing a node inside one, and leaving them out
+    // would make this set mean two different things depending on which caller
+    // read it.
+    'popup',
+    'menu-panel',
+    'menu-drawer',
+]);
+/** Is this node an overlay for RENDER purposes — composed, or one by type? */
+export function isOffscreenOverlay(doc, id) {
+    if (isOverlay(doc, id))
+        return true;
+    return OFFSCREEN_UNTIL_OPEN.has(doc.nodes[id]?.data.type ?? '');
+}
+/**
+ * Every node inside an overlay on this page, for a caller that must not judge
+ * their geometry.
+ *
+ * ROOT's children only, matching where an overlay may legally sit — and a
+ * by-type overlay nested deeper is deliberately not swept up, because a
+ * `popup` inside a section is a document the platform refuses on save and
+ * hiding it here would hide that.
+ */
+export function offscreenNodes(doc) {
+    const out = new Set();
+    for (const id of childrenOf(doc, doc.root_node_id)) {
+        if (!isOffscreenOverlay(doc, id))
+            continue;
+        for (const n of subtreeIds(doc, id))
+            out.add(n);
+    }
+    return out;
+}
+/**
+ * The overlay this node sits in, for the RENDER question "what must be opened
+ * before I can photograph this".
+ *
+ * Deliberately NOT `overlayRoot` from core/tree, and deliberately not a change
+ * to it: that one answers the COMPOSITION question every write guard asks —
+ * "is this node inside a subtree the save will strip" — and widening it to
+ * element types would make `refuseOverlay` start refusing writes to a plain
+ * authored drawer, which is a node this page genuinely owns and may edit.
+ * Two questions, two functions.
+ */
+export function offscreenRootOf(doc, id) {
+    const roots = childrenOf(doc, doc.root_node_id).filter((k) => isOffscreenOverlay(doc, k));
+    for (const root of roots) {
+        if (root === id || subtreeIds(doc, root).includes(id))
+            return root;
+    }
+    return null;
+}

package/dist/domains/site/pagestate.js

@@ -0,0 +1,116 @@
+/**
+ * WHICH OF THIS PAGE'S THREE COPIES IS WHICH.
+ *
+ * A page is not one document. It is three, read by three different consumers,
+ * and every tool here answered for one of them while a caller was asking about
+ * another:
+ *
+ *   - the DRAFT  — `GET /pages/{id}/source`. What the EDITOR CANVAS shows.
+ *   - the PUBLISHED row — compiled at publish time. What the STOREFRONT serves.
+ *   - this SESSION's copy — read once into memory and edited since.
+ *
+ * "The render has data but the canvas is blank" is the shape this exists for,
+ * and it is not a cache: it is the draft having been emptied while the
+ * published row kept the good copy. This repo has the measured incident — a
+ * product template of 24 nodes read back bare, stored bare; the published copy
+ * untouched, so all 19 product pages went on rendering; invisible until a
+ * person opened the editor. `PageSession.save` guards the session that CAUSES
+ * that, and nothing reported a draft that was already in that state.
+ *
+ * THE CANVAS GATE IS SIMULATED RATHER THAN DESCRIBED, because the editor's
+ * rule is three lines and nothing else can answer it
+ * (`editor/src/stores/node.ts`, `hydrate`):
+ *
+ *     const nodes = doc?.nodes ?? {};
+ *     const rootId = doc?.root_node_id ?? '';
+ *     if (!rootId || !nodes[rootId]) { this.seedRoot(opts?.pageId); return; }
+ *
+ * A document failing it is SILENTLY REPLACED by an empty ROOT — blank canvas,
+ * no error anywhere — and the editor's next save stores that blank. The Go
+ * renderer has no such gate, so a document can fail this and still publish
+ * markup, which is exactly how the two copies come apart.
+ *
+ * READ AGAINST THE RAW DOCUMENT, never against a `PageDoc`. `PageDoc.from`
+ * ADOPTS a `rootId`/`rootNodeId` alias and repairs it in memory, which is the
+ * right thing for a tool that is about to edit the page and the wrong thing
+ * for a report about what the editor will do: the editor reads the stored
+ * bytes, and the stored bytes still carry the alias.
+ */
+export function canvasVerdict(document) {
+    const d = (document ?? {});
+    const nodes = (d.nodes ?? {});
+    const count = Object.keys(nodes).length;
+    const root = typeof d.root_node_id === 'string' ? d.root_node_id : '';
+    if (root && nodes[root])
+        return { blank: false, nodes: count };
+    // THE ALIAS IS WORTH NAMING SEPARATELY, because the repair is one save and
+    // the reader otherwise has no idea why a document with plenty of nodes is
+    // about to vanish. `rootId` is the key an app block and a section template
+    // use for the same idea, and the editor's own completion-page seed shipped
+    // it (`element/completionPage.ts:91`, fixed upstream in 8e40bbab) — so pages
+    // created from that seed still carry it today.
+    const alias = ['rootId', 'rootNodeId'].find((k) => typeof d[k] === 'string' && nodes[d[k]]);
+    if (alias) {
+        return {
+            blank: true,
+            nodes: count,
+            why: `The document names its root under "${alias}" instead of root_node_id, so the editor ` +
+                `discards all ${count} nodes and shows an empty canvas, and the Go renderer publishes ` +
+                'an empty <body> with a 200.',
+            fix: 'sb_page_open adopts the alias and the next save writes the canonical key: open the ' +
+                'page, make any edit (or none — sb_page_open reports blank_page_repair), save, publish.',
+        };
+    }
+    if (count === 0) {
+        return {
+            blank: true,
+            nodes: 0,
+            why: 'The document holds no nodes at all. For a page just created this is normal.',
+            fix: 'Build it — sb_template_use for a designed band, or sb_add from ROOT.',
+        };
+    }
+    return {
+        blank: true,
+        nodes: count,
+        why: `root_node_id is ${JSON.stringify(d.root_node_id ?? null)}, which names none of the ` +
+            `${count} nodes present. The editor discards the whole document and shows an empty ` +
+            'canvas; its next save would store that blank over these nodes.',
+        fix: 'Do NOT open and save this page in the editor until it is repaired — that save is what ' +
+            'makes the loss permanent. Recover the draft from a page version or from the published ' +
+            'copy (sb_api_find "page versions").',
+    };
+}
+export function driftOf(draftUpdatedAt, publishedAt) {
+    if (!publishedAt) {
+        return {
+            state: 'never_published',
+            note: 'This page has no published copy, so nothing is served for it — the URL 404s.',
+        };
+    }
+    if (!draftUpdatedAt) {
+        return { state: 'in_step', note: 'The draft reports no timestamp to compare.' };
+    }
+    const draft = Date.parse(draftUpdatedAt);
+    const live = Date.parse(publishedAt);
+    if (!Number.isFinite(draft) || !Number.isFinite(live)) {
+        return { state: 'in_step', note: 'One of the timestamps could not be read.' };
+    }
+    // A SECOND of slack. Publish writes its own row after reading the draft, so
+    // the two are legitimately microseconds apart on an untouched page and
+    // reporting that as "unpublished changes" would cry wolf on every check.
+    if (draft > live + 1000) {
+        return {
+            state: 'draft_ahead',
+            note: 'The draft has changes the live page does not. The editor canvas and the storefront ' +
+                'will disagree until this page is published.',
+        };
+    }
+    if (live > draft + 1000) {
+        return {
+            state: 'published_ahead',
+            note: 'The live page is NEWER than the draft. That happens on a cascaded publish — a shared ' +
+                'header edited elsewhere republishes every page carrying it — and is not a defect.',
+        };
+    }
+    return { state: 'in_step', note: 'The draft and the live page are the same revision.' };
+}