sbuilder-mcp 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -6,6 +6,17 @@ 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.4.2] - 2026-09-08
+
+### Changed
+- sb_look now waits for the page to stop changing (a MutationObserver, 250 ms quiet / 2000 ms cap) instead of waiting on a networkidle timeout that a storefront's polling cart island and session checks could never satisfy, cutting a typical shot from ~3.2s to under 1s while still photographing a page that never settles rather than holding the shot forever.
+
+## [0.4.1] - 2026-09-08
+
+### Fixed
+- sb_review now reports findings inside the cart drawer and other site overlays, tagged with overlay: true, instead of silently skipping them on the belief that an overlay is not the page's to fix; the review notice explains that an overlay:true finding is fixed the same way but is site-wide, so it only needs fixing once.
+- sb_api_call's path_params now matches a parameter name case-insensitively as a fallback, so a call using the common siteId spelling no longer fails against the 8 operations that spell it siteID; an exact match still wins and a genuinely missing parameter is still refused.
+
 ## [0.4.0] - 2026-09-08
 
 ### Added

package/CHANGELOG.vi.md

@@ -6,6 +6,17 @@ 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.4.2] - 2026-09-08
+
+### Changed
+- sb_look giờ chờ trang ngừng thay đổi (dùng MutationObserver, 250 ms yên tĩnh / giới hạn 2000 ms) thay vì chờ timeout networkidle mà cart island liên tục polling và các kiểm tra session của storefront không bao giờ thỏa mãn được, rút ngắn một lần chụp điển hình từ ~3.2s xuống dưới 1s, đồng thời vẫn chụp ảnh một trang không bao giờ ổn định thay vì giữ mãi không chụp.
+
+## [0.4.1] - 2026-09-08
+
+### Fixed
+- sb_review giờ báo cáo các finding bên trong cart drawer và các overlay khác của site, gắn cờ overlay: true, thay vì âm thầm bỏ qua chúng vì cho rằng một overlay không phải trách nhiệm của trang; thông báo review giải thích rằng một finding có overlay: true được sửa theo cùng cách nhưng có phạm vi toàn site, nên chỉ cần sửa một lần.
+- path_params của sb_api_call giờ khớp tên tham số không phân biệt hoa thường như một phương án dự phòng, nên một lời gọi dùng cách viết phổ biến siteId không còn thất bại với 8 operation viết là siteID; một khớp chính xác vẫn được ưu tiên và một tham số thực sự thiếu vẫn bị từ chối.
+
 ## [0.4.0] - 2026-09-08
 
 ### Added

package/dist/domains/site/review.js

@@ -12,7 +12,9 @@ import { fill } from './findings.js';
 export const REVIEW_NOTICE = 'FIX THESE. Each one is a defect a visitor will see on the published page, not a ' +
     'suggestion — a blank band, a placeholder sentence, a broken image. Apply the fix each ' +
     '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.';
+    '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.';
 /** The specials keys an element seeds that hold its visible content. */
 function contentKeys(type) {
     const seeded = ELEMENTS[type]?.defaults.specials ?? {};
@@ -56,8 +58,19 @@ function drawsItsOwnContent(type) {
 /**
  * Everything wrong with this page that a person would notice.
  *
- * Overlays are skipped: the cart drawer is composed onto ROOT on read and is not
- * this page's to fix. So is the INSIDE of an app block (trap 5): its
+ * OVERLAYS ARE WALKED, and used not to be — on the stated reasoning that the
+ * cart drawer "is not this page's to fix", which is false. An overlay's content
+ * reaches storage THROUGH THE PAGE SAVE (`overlays/rest/rest.go`: content is
+ * "deliberately NOT written here"), so `sb_set` on a drawer node lands, and the
+ * skip meant nothing ever reported what shipped inside one. Measured: a
+ * rose-and-ink storefront whose drawer carried a static mock row reading
+ * "Product name / 0₫", a duplicate cart list, and English copy — none of it
+ * mentioned by any check, on a site that reviewed clean ten pages running.
+ *
+ * Their findings carry `overlay: true`, because the master is SHARED: without
+ * the flag the same drawer defect reads as ten problems on a ten-page site.
+ *
+ * The INSIDE of an app block is still skipped (trap 5): its
  * placeholders are the app's, and no fix this page could apply would survive a
  * save. The block root itself is still walked — it is a node the page owns and
  * can be an empty container. Findings are ordered by document order so a caller working
@@ -84,10 +97,14 @@ export function reviewDesign(doc) {
     // itself belongs to the scope OUTSIDE it, which is why this is set before the
     // scope for the children is computed.
     const inRepeater = new Map();
-    const go = (id, repeater) => {
-        if (seen.has(id) || overlayIds.has(id))
+    // Which nodes sit inside an overlay, so their findings can say so.
+    const inOverlay = new Set();
+    const go = (id, repeater, overlay = false) => {
+        if (seen.has(id))
             return;
         seen.add(id);
+        if (overlay)
+            inOverlay.add(id);
         walkOrder.push(id);
         if (repeater)
             inRepeater.set(id, repeater);
@@ -95,7 +112,7 @@ export function reviewDesign(doc) {
             return;
         const inner = repeats(d.nodes[id]?.data.type ?? '') ? (repeater ?? id) : repeater;
         for (const k of childrenOf(d, id))
-            go(k, inner);
+            go(k, inner, overlay || overlayIds.has(k));
     };
     go(d.root_node_id);
     for (const id of walkOrder) {
@@ -301,5 +318,12 @@ export function reviewDesign(doc) {
             }
         }
     }
+    // Tagged in ONE place rather than at eight push sites: whether a node sits
+    // inside an overlay is a fact about where it is, not about what is wrong with
+    // it, and threading it through every rule would put the same argument in eight
+    // signatures.
+    for (const f of out)
+        if (inOverlay.has(f.nodeId))
+            f.overlay = true;
     return out;
 }

package/dist/tools/api.js

@@ -171,7 +171,19 @@ export async function callOperation(ctx, args) {
     let path = op.path;
     for (const m of op.path.matchAll(/\{([^}]+)\}/g)) {
         const name = m[1];
-        const value = args.path_params?.[name];
+        // CASE-INSENSITIVE, because the platform spells one parameter two ways:
+        // `{siteId}` in 281 operations and `{siteID}` in 8. A caller who learned the
+        // common spelling passes the wrong key on those eight and is refused for a
+        // difference of one letter — a distinction no reader of the call sheet has
+        // any reason to notice, and one this tool has nothing to gain by enforcing.
+        // The exact name still wins; the fold is only a fallback.
+        const given = args.path_params ?? {};
+        let value = given[name];
+        if (value === undefined) {
+            const folded = Object.keys(given).find((k) => k.toLowerCase() === name.toLowerCase());
+            if (folded !== undefined)
+                value = given[folded];
+        }
         if (value === undefined) {
             // NAME THE ARGUMENT, not just the parameter. The call sheet lists these
             // under `params` while the call takes them in `path_params`, and a caller

package/dist/vision/shoot.js

@@ -138,6 +138,54 @@ export async function shoot(url, opts = {}) {
         }
     }));
 }
+/**
+ * WAIT FOR THE PAGE TO STOP CHANGING, not for the network to go quiet.
+ *
+ * This used to be `waitForLoadState('networkidle', { timeout: 2_500 })`, with a
+ * comment explaining that a storefront never goes idle — the cart island polls,
+ * a session endpoint answers 401 forever. That was correct, and it meant the
+ * wait ALWAYS ran to its cap: measured at 2502 ms on every single look, three
+ * runs out of three, against a 2847 ms total. Eighty-eight per cent of a
+ * screenshot was a timeout the code already knew would never resolve, paid after
+ * every edit of a vision loop.
+ *
+ * A MutationObserver answers the question actually being asked — has the page
+ * finished rendering — and answers it the moment it is true. Measured on the
+ * same three pages: 400-460 ms, with identical content on screen (images,
+ * prices, no empty states). The storefront renders its lists SERVER-side, so
+ * everything is present a few hundred ms after `load`; the old wait bought
+ * nothing but latency.
+ *
+ * Bounded twice over, and both bounds matter: `quiet` is how long nothing may
+ * change before the page counts as settled, and `cap` stops an animation or a
+ * polling widget from holding the shot forever. A page that never settles is
+ * photographed anyway — a late picture beats none.
+ */
+async function settleDom(page) {
+    await page
+        .evaluate(({ quiet, cap }) => new Promise((resolve) => {
+        const start = Date.now();
+        let last = Date.now();
+        const mo = new MutationObserver(() => {
+            last = Date.now();
+        });
+        mo.observe(document.documentElement, {
+            subtree: true,
+            childList: true,
+            attributes: true,
+            characterData: true,
+        });
+        const tick = setInterval(() => {
+            const now = Date.now();
+            if (now - last >= quiet || now - start >= cap) {
+                clearInterval(tick);
+                mo.disconnect();
+                resolve();
+            }
+        }, 50);
+    }), { quiet: 250, cap: 2_000 })
+        .catch(() => { });
+}
 /**
  * WALK THE PAGE so its lazy images load, then come back to the top.
  *
@@ -187,7 +235,7 @@ async function shootOne(page, url, width, format, opts) {
     // storefront. The settle is best-effort: if the page does go quiet, the shot
     // waits for it; if it never does, the shot happens anyway.
     await page.goto(url, { waitUntil: 'load', timeout: 30_000 });
-    await page.waitForLoadState('networkidle', { timeout: 2_500 }).catch(() => { });
+    await settleDom(page);
     await settleLazyImages(page);
     // A RENDERED page carries its node ids as the HTML `id` attribute — not as
     // `data-node-id`, which is the editor CANVAS's hook and never reaches the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sbuilder-mcp",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "MCP server that designs and operates a Store Builder site — pages, data, theme and publish — through the platform's own API and live-edit protocol.",
   "mcpName": "io.github.vuluu2k/sbuilder-mcp",
   "type": "module",