sbuilder-mcp 0.40.0 → 0.41.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.41.0] - 2026-09-13
+
+### Added
+- `sb_templates` / `sb_template_use` gain four new built-in layout patterns — `sb_product_shelf` and `sb_category_strip` are real `list-dataset` repeaters bound to the catalogue rather than static tiles, `sb_brand_wall` frames library logos with `contain` instead of a photograph's median-ratio crop, and `sb_trust_band` composes icon-plus-line reassurances from exact platform icon ids.
+- `sb_api_find` and `sb_api_call` now attach a `product_traps` note to the four operations that create or replace a whole product, naming three facts a `ProductInput` body cannot show on its own: price lives on the variant rather than the product, a colliding slug is silently renamed rather than refused, and an image can be ingested straight from a URL in one hop.
+- The inert-element table grew from 3 to 20 entries after an audit of all 113 catalog elements, adding `quickview`, `bundle-items`, `chat-widget`, `currency-switcher`, `theme-switcher`, `form-step-count`, `form-step-button`, `order-receipt`, `payment-status`, `points-card`, `points-prompt`, `list-empty`, `list-loading`, `rating-stars`, `accordion-content`, `menu-drawer` and `menu-panel` — elements that render convincingly on the first write while doing nothing useful, so `sb_add` can now warn about them before publish.
+- `sb_import_site` now reads a sitemap index's own child filenames to tell record pages (products, categories, brands, tags) from page-shaped ones, and excludes the record kinds from the import plan by default instead of picking whichever URLs happen to win the page cap.
+
+### Fixed
+- `sb_import` and `sb_import_site` no longer turn an `<svg>`'s wrapper or utility class into a confident wrong icon; a class candidate is only considered when it carries a prefix a real icon set actually stamps, ranked by length only as a tie-break among those.
+- `sb_import` and `sb_import_site` now build a captured list as a real `list` of `list-item` nodes carrying the platform's own marker icon, instead of a column of text nodes each with a literal bullet glyph glued on.
+- The `structure` fidelity score no longer reports arrangement loss on pages with lists; the shape comparison now counts a captured list's rows as real children instead of scoring the list as an empty leaf.
+- `sb_import_site`'s theme write and its per-node color/font-size stamping no longer fight each other; the four token fields a default style preset already resolves through the theme are dropped from the stamped literals once the theme write actually lands, so an imported page's colors stay controlled by the theme instead of a literal that silently outranks it forever.
+- The `coverage` score reported by `sb_import` and `sb_import_site` no longer counts text the importer deliberately declines (chrome, hidden elements, form controls, decorative content) as lost content, and no longer misses text in a bare top-level `<nav>` or a hidden `<select>` that the page-section walk never visits at all.
+
 ## [0.40.0] - 2026-09-13
 
 ### 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.41.0] - 2026-09-13
+
+### Added
+- `sb_templates` / `sb_template_use` có thêm bốn layout dựng sẵn — `sb_product_shelf` và `sb_category_strip` là repeater `list-dataset` thật, gắn vào catalogue thay vì các ô tĩnh; `sb_brand_wall` đóng khung logo lấy từ thư viện bằng `contain` thay vì crop theo tỉ lệ trung vị của ảnh chụp; `sb_trust_band` ghép các dòng cam kết icon-kèm-chữ từ đúng các id icon của nền tảng.
+- `sb_api_find` và `sb_api_call` giờ đính kèm ghi chú `product_traps` vào bốn operation tạo hoặc thay thế toàn bộ một sản phẩm, nêu rõ ba điều mà body `ProductInput` không tự nói lên được: giá nằm ở variant chứ không phải ở product, một slug trùng bị đổi tên âm thầm chứ không bị từ chối, và có thể nạp ảnh thẳng từ URL trong một bước thay vì hai.
+- Bảng phần tử "inert" tăng từ 3 lên 20 mục sau khi rà soát toàn bộ 113 phần tử trong catalog, thêm `quickview`, `bundle-items`, `chat-widget`, `currency-switcher`, `theme-switcher`, `form-step-count`, `form-step-button`, `order-receipt`, `payment-status`, `points-card`, `points-prompt`, `list-empty`, `list-loading`, `rating-stars`, `accordion-content`, `menu-drawer` và `menu-panel` — những phần tử trông có vẻ hoàn chỉnh ngay ở lần ghi đầu tiên nhưng không làm được gì cả, nên `sb_add` giờ có thể cảnh báo về chúng trước khi publish.
+- `sb_import_site` giờ đọc tên file của từng sitemap con trong một sitemap index để phân biệt trang dữ liệu (sản phẩm, danh mục, thương hiệu, tag) với trang nội dung thông thường, và mặc định loại các trang dữ liệu khỏi kế hoạch import thay vì chọn đại URL nào thắng giới hạn số trang.
+
+### Fixed
+- `sb_import` và `sb_import_site` không còn biến class wrapper hay class tiện ích của một `<svg>` thành một icon sai nhưng trông chắc chắn đúng; một class chỉ được xét khi mang tiền tố mà một bộ icon thật sự dùng, và chỉ xếp hạng theo độ dài như một cách phân định giữa các ứng viên đó.
+- `sb_import` và `sb_import_site` giờ dựng một danh sách đã capture thành `list` thật gồm các `list-item`, mang icon đánh dấu riêng của nền tảng, thay vì một cột các node văn bản mỗi cái gắn cứng một ký tự bullet.
+- Điểm `structure` trong đo lường fidelity không còn báo mất cấu trúc trên các trang có danh sách; phép so sánh hình dạng giờ tính các dòng của một danh sách đã capture là con thật thay vì tính danh sách đó như một lá rỗng.
+- Bản ghi theme của `sb_import_site` và việc gán màu/cỡ chữ literal lên từng node không còn triệt tiêu lẫn nhau; bốn field token mà một style preset mặc định vốn đã phân giải qua theme sẽ bị bỏ khỏi các literal được gán ngay khi bản ghi theme thực sự có hiệu lực, nhờ đó màu sắc của trang được import vẫn do theme kiểm soát thay vì một literal âm thầm đè lên nó mãi mãi.
+- Điểm `coverage` mà `sb_import` và `sb_import_site` báo cáo không còn tính phần chữ mà importer chủ động bỏ qua (chrome, phần tử ẩn, control của form, nội dung trang trí) là nội dung bị mất, và không còn bỏ sót chữ nằm trong một `<nav>` cấp cao nhất hay một `<select>` ẩn mà lượt duyệt theo section chưa bao giờ chạm tới.
+
 ## [0.40.0] - 2026-09-13
 
 ### Added

package/README.md

@@ -94,7 +94,7 @@ in this client: one would put the very key the platform exists to hold back into
 | `sb_move` | Move a node to another parent |
 | `sb_remove` | Remove a node and its subtree |
 | `sb_duplicate` | Copy a node and its subtree under fresh ids, right after the original |
-| `sb_templates` | The store's saved section templates, plus the BUILT-IN layouts — hero, feature trio, stats, FAQ, CTA band — composed against the page's own tokens |
+| `sb_templates` | The store's saved section templates, plus the BUILT-IN layouts — hero, feature trio, stats, FAQ, CTA band, product shelf, category strip, brand wall, trust band — composed against the page's own tokens |
 | `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 |
@@ -113,7 +113,7 @@ in this client: one would put the very key the platform exists to hold back into
 | `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, **524 API operations** (175 of the 234 writes carrying a body shape read
-off the handler), 112 elements, 78 binding sources. `sb_api_find`
+off the handler), 113 elements, 78 binding sources. `sb_api_find`
 is an index rather than a tool per endpoint, so the tool list stays short while everything
 the platform can do stays reachable — and operations added to the platform arrive with the
 next `npm run codegen`.

package/README.vi.md

@@ -91,7 +91,7 @@ nhét ngược lại vào mọi bản cài.
 | `sb_move` | Chuyển node sang cha khác |
 | `sb_remove` | Xoá node và cả cây con |
 | `sb_duplicate` | Nhân bản một node và cả cây con dưới id mới, ngay sau bản gốc |
-| `sb_templates` | Section template đã lưu của cửa hàng, cộng bộ layout DỰNG SẴN — hero, ba lợi ích, số liệu, FAQ, dải kêu gọi — soạn theo token của chính trang |
+| `sb_templates` | Section template đã lưu của cửa hàng, cộng bộ layout DỰNG SẴN — hero, ba lợi ích, số liệu, FAQ, dải kêu gọi, kệ sản phẩm, dải danh mục, dải logo, dải cam kết — soạn theo token của chính trang |
 | `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 |
@@ -110,7 +110,7 @@ nhét ngược lại vào mọi bản cài.
 | `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, **524 operation API** (175 trong 234 lệnh ghi có hình dạng body đọc thẳng
-từ handler), 112 element, 78 nguồn binding. `sb_api_find` là
+từ handler), 113 element, 78 nguồn binding. `sb_api_find` là
 một chỉ mục chứ không phải mỗi endpoint một tool, nên danh sách tool vẫn ngắn trong khi mọi
 thứ nền tảng làm được vẫn với tới — và operation mới thêm bên nền tảng sẽ tự có sau lần
 `npm run codegen` kế tiếp.

package/dist/catalog/elements.generated.js

@@ -1,5 +1,5 @@
 export const ELEMENT_SOURCE = {
-    "count": 112,
+    "count": 113,
     "docSchemaVersion": 2
 };
 export const ELEMENTS = {
@@ -689,7 +689,9 @@ export const ELEMENTS = {
                 "close_dropdown",
                 "toggle_dropdown",
                 "logout_customer",
-                "toggle_wishlist"
+                "toggle_wishlist",
+                "quick_view",
+                "close_quick_view"
             ]
         },
         "bindingEvents": {
@@ -1592,7 +1594,9 @@ export const ELEMENTS = {
                 "change_tab",
                 "open_dropdown",
                 "close_dropdown",
-                "toggle_dropdown"
+                "toggle_dropdown",
+                "quick_view",
+                "close_quick_view"
             ]
         },
         "defaults": {
@@ -1762,7 +1766,9 @@ export const ELEMENTS = {
                 "close_dropdown",
                 "toggle_dropdown",
                 "logout_customer",
-                "toggle_wishlist"
+                "toggle_wishlist",
+                "quick_view",
+                "close_quick_view"
             ]
         },
         "defaults": {
@@ -3688,7 +3694,7 @@ export const ELEMENTS = {
     },
     "spline-scene": {
         "type": "spline-scene",
-        "label": "Spline scene",
+        "label": "3D scene",
         "category": "media",
         "isContainer": false,
         "isRootOnly": false,
@@ -3697,6 +3703,7 @@ export const ELEMENTS = {
         "childAllows": [],
         "defaults": {
             "specials": {
+                "source": "effect",
                 "sceneUrl": "https://prod.spline.design/HqdfCmOueigtautT/scene.splinecode",
                 "posterUrl": "",
                 "sceneControls": []
@@ -3708,13 +3715,28 @@ export const ELEMENTS = {
             "config": {
                 "background": "transparent",
                 "eventsTarget": "local",
-                "mobileMode": "scene"
+                "mobileMode": "scene",
+                "effect": "gradient-mesh",
+                "speed": "normal",
+                "intensity": "normal",
+                "grain": false,
+                "effectColors": "theme",
+                "effectColor1": "#171717",
+                "effectColor2": "#ffffff",
+                "effectColor3": "#6b7280"
             }
         },
         "inspector": [
             {
                 "tab": "general",
                 "groups": [
+                    {
+                        "key": "scene_source",
+                        "label": "Source",
+                        "controls": [
+                            "scene_source"
+                        ]
+                    },
                     {
                         "key": "size",
                         "label": "Size",
@@ -3730,6 +3752,13 @@ export const ELEMENTS = {
                             "spline_source"
                         ]
                     },
+                    {
+                        "key": "scene_effect",
+                        "label": "Effect",
+                        "controls": [
+                            "scene_effect"
+                        ]
+                    },
                     {
                         "key": "scene_display",
                         "label": "Display",
@@ -3790,9 +3819,11 @@ export const ELEMENTS = {
             }
         ],
         "controls": [
+            "scene_source",
             "width_select",
             "size_bounds",
             "spline_source",
+            "scene_effect",
             "scene_display",
             "scene_controls",
             "border",
@@ -3803,25 +3834,35 @@ export const ELEMENTS = {
             "animation",
             "class_css"
         ],
-        "description": "An interactive 3D scene made in Spline, embedded from its viewer URL.",
+        "description": "A 3D block whose source the merchant picks: a generated WebGL effect that needs no file and no account (~15 KB), or a Spline scene embedded from its viewer link (~600 KB).",
         "useWhen": [
+            "For a moving background behind a hero or a section — pick the effect source, which costs ~15 KB and needs nothing but the element",
             "For a hero or product moment that should move in 3D as the visitor scrolls or hovers",
-            "When the merchant already designs in Spline and has a .splinecode link"
+            "When the merchant already designs in Spline and has a .splinecode link — pick the Spline source"
         ],
         "avoidWhen": [
             "For a plain product photo — use image",
             "For a video — use video / youtube / vimeo",
-            "More than three 3D scenes on one page (each one costs ~600 KB of JS once it scrolls into view)"
+            "For a still gradient or a flat colour behind text — a background style on the section is free; this element runs a shader",
+            "More than one Spline scene on a page (each costs ~600 KB of JS once it scrolls into view). Several effects are cheap by comparison, but they each run their own animation loop"
         ],
         "contentTips": [
-            "Paste the link from Spline: Export → Viewer → copy link (…/scene.splinecode)",
-            "Add a poster image so the box is not blank while the scene loads"
+            "Choose the source first — the rest of the panel changes with it, and the budget line under the picker says what the page will download",
+            "Effect: four shaders (gradient mesh, floating particles, waves, aurora) with speed, intensity and a grain toggle. Its colours follow the site theme until you switch them to custom",
+            "Spline: paste the link from Spline — Export → Viewer → copy link (…/scene.splinecode)",
+            "Add a poster image so the box is not blank while a Spline scene loads; an effect draws immediately and needs none",
+            "Scene controls (rotate on scroll, tilt with the mouse) drive named objects, so they apply to a Spline scene and not to an effect, which has no objects"
         ],
         "semantics": [
             "3d",
             "spline",
             "scene",
             "webgl",
+            "shader",
+            "effect",
+            "gradient",
+            "particles",
+            "animated background",
             "animation",
             "interactive"
         ]
@@ -19567,6 +19608,190 @@ export const ELEMENTS = {
             "input-skin"
         ]
     },
+    "quickview": {
+        "type": "quickview",
+        "label": "Quick view",
+        "category": "basic",
+        "isContainer": true,
+        "isRootOnly": false,
+        "locked": true,
+        "hideInLayer": false,
+        "childAllows": [],
+        "defaults": {
+            "style": {
+                "display": "flex",
+                "flexDirection": "column",
+                "gap": "16px",
+                "width": "720px",
+                "maxWidth": "calc(100% - 32px)",
+                "maxHeight": "calc(100vh - 64px)",
+                "padding": "24px",
+                "backgroundColor": "#ffffff",
+                "borderTopLeftRadius": "10px",
+                "borderTopRightRadius": "10px",
+                "borderBottomLeftRadius": "10px",
+                "borderBottomRightRadius": "10px",
+                "overflowX": "hidden",
+                "overflowY": "auto"
+            },
+            "config": {
+                "showOverlay": true,
+                "overlayColor": "#000000",
+                "clickToClose": true
+            }
+        },
+        "inspector": [
+            {
+                "tab": "general",
+                "groups": [
+                    {
+                        "key": "panel",
+                        "label": "Panel",
+                        "controls": [
+                            "quickview_name"
+                        ]
+                    },
+                    {
+                        "key": "size",
+                        "label": "Size",
+                        "controls": [
+                            "width_select",
+                            "height_select",
+                            "size_bounds"
+                        ]
+                    },
+                    {
+                        "key": "layout",
+                        "label": "Layout",
+                        "controls": [
+                            "direction",
+                            "gap",
+                            "padding",
+                            "margin",
+                            "vertical",
+                            "horizontal"
+                        ]
+                    },
+                    {
+                        "key": "quickview_position",
+                        "label": "Position",
+                        "controls": [
+                            "popup_placement"
+                        ]
+                    },
+                    {
+                        "key": "quickview_overlay",
+                        "label": "Overlay",
+                        "controls": [
+                            "quickview_scrim"
+                        ]
+                    },
+                    {
+                        "key": "background",
+                        "label": "Background",
+                        "controls": [
+                            "bg_color",
+                            "bg_image"
+                        ]
+                    },
+                    {
+                        "key": "shape",
+                        "label": "Shape",
+                        "controls": [
+                            "border",
+                            "corner",
+                            "shadow"
+                        ]
+                    }
+                ]
+            },
+            {
+                "tab": "advanced",
+                "groups": [
+                    {
+                        "key": "state",
+                        "label": "state",
+                        "controls": []
+                    },
+                    {
+                        "key": "spacing",
+                        "label": "Spacing",
+                        "controls": [
+                            "padding_margin"
+                        ]
+                    },
+                    {
+                        "key": "display",
+                        "label": "Display",
+                        "controls": [
+                            "display"
+                        ]
+                    },
+                    {
+                        "key": "animation",
+                        "label": "Animation",
+                        "controls": [
+                            "animation"
+                        ]
+                    },
+                    {
+                        "key": "class_css",
+                        "label": "Class",
+                        "controls": [
+                            "class_css"
+                        ]
+                    }
+                ]
+            }
+        ],
+        "controls": [
+            "quickview_name",
+            "width_select",
+            "height_select",
+            "size_bounds",
+            "direction",
+            "gap",
+            "padding",
+            "margin",
+            "vertical",
+            "horizontal",
+            "popup_placement",
+            "quickview_scrim",
+            "bg_color",
+            "bg_image",
+            "border",
+            "corner",
+            "shadow",
+            "padding_margin",
+            "display",
+            "animation",
+            "class_css"
+        ],
+        "description": "A QUICK VIEW panel: the surface a shopper opens from a product card to see enough to decide — gallery, title, price, variants, quantity, add to cart — without leaving the list they were browsing. Belongs to the site, not to a page; a product list points at one and several lists may share the same panel.",
+        "useWhen": [
+            "a catalogue page where shoppers compare several products and losing their scroll position costs a sale",
+            "a store whose products need one or two choices (size, colour) before they can be added to the cart",
+            "a site that wants a second, shorter product surface without maintaining a second product page"
+        ],
+        "avoidWhen": [
+            "as a standalone block: this panel only renders through the list that names it, hidden until a shopper opens it",
+            "as a replacement for the product page — search engines index the page, not this panel, and a long description belongs there",
+            "for products that need no decision at all: a one-click add-to-cart button on the card is faster than any panel"
+        ],
+        "contentTips": [
+            "show what the card could not: the other photos, the variants, the stock, the short description",
+            "keep an obvious way through to the full product page — a shopper who wants the detail should not have to close and hunt",
+            "put the add-to-cart control where it is visible without scrolling on a phone"
+        ],
+        "semantics": [
+            "quick-view",
+            "modal",
+            "product",
+            "listing",
+            "commerce",
+            "container"
+        ]
+    },
     "product-variants": {
         "type": "product-variants",
         "label": "Product variants",
@@ -32802,6 +33027,14 @@ export const ELEMENTS = {
                             "loadingStateId"
                         ]
                     },
+                    {
+                        "key": "quickview",
+                        "label": "Quick view",
+                        "controls": [
+                            "list_quickview",
+                            "quickviewId"
+                        ]
+                    },
                     {
                         "key": "narrowing",
                         "label": "Narrowing",
@@ -32963,6 +33196,8 @@ export const ELEMENTS = {
             "list_loading_state",
             "emptyStateId",
             "loadingStateId",
+            "list_quickview",
+            "quickviewId",
             "list_searchable",
             "list_filterable",
             "width_select",
@@ -36111,6 +36346,11 @@ export const SATELLITE_RULES = {
             "type": "list-loading",
             "configKey": "loadingStateId",
             "optional": true
+        },
+        {
+            "type": "quickview",
+            "configKey": "quickviewNodeId",
+            "optional": true
         }
     ]
 };
@@ -36336,6 +36576,11 @@ export const BASE_ONLY_CONFIG = [
     "collectionId",
     "collectionType",
     "quantity",
+    "effect",
+    "speed",
+    "intensity",
+    "grain",
+    "effectColors",
     "rowLimit"
 ];
 /**

package/dist/catalog/search.js

@@ -13,6 +13,20 @@ import { translationCallSheet } from '../domains/site/translate.js';
 const WEIGHT = { tag: 5, path: 3, summary: 2 };
 /** Eight is enough to choose from; twelve was measured at 44 KB once the schemas rode along. */
 export const DEFAULT_FIND_LIMIT = 8;
+/**
+ * The four operations that create or replace a whole product, on both
+ * credential surfaces — never a list, a delete, or the bulk import/categories
+ * routes beside them. Listed rather than matched by path pattern, because
+ * `/products/import` and `/products/{productId}/categories` sit right next to
+ * these and are not this trap: an import posts a file, and filing a product
+ * under a category touches neither its price, its slug, nor its photos.
+ */
+const PRODUCT_WRITE_IDS = new Set([
+    'post:/api/sites/{siteId}/products',
+    'put:/api/sites/{siteId}/products/{id}',
+    'post:/api/v1/products',
+    'put:/api/v1/products/{id}',
+]);
 export function findOperation(id) {
     return API_OPERATIONS.find((o) => o.id === id);
 }
@@ -139,6 +153,20 @@ export function describeOperation(op) {
                 '/apps/blocks again for what it contributed.',
         };
     }
+    // FILLING A CATALOGUE WAS REACHABLE AND THREE FACTS ABOUT IT WERE NOT, each
+    // failing silently. Attached to the call sheet for the same reason the
+    // translation table is: this is where the agent is when it decides what to
+    // send, on both credential surfaces a product can be created or replaced on.
+    if (PRODUCT_WRITE_IDS.has(op.id)) {
+        out.product_traps = {
+            price: 'Price lives on the VARIANT, not the product — variants[].priceCents. A product ' +
+                'posted with no variant renders a catalogue entry nobody can buy.',
+            slug: 'A colliding slug is RENAMED, not refused, and the write still answers 200/201. ' +
+                'Re-running an import does not error — it DOUBLES the catalogue in silence.',
+            images: 'POST /api/media/{siteId}/from-url ingests a photo straight from its URL, one hop ' +
+                'instead of downloading and re-uploading it.',
+        };
+    }
     const shape = REQUEST_SHAPES[op.id];
     if (shape) {
         out.body_shape = shape;

package/dist/domains/site/discover.js

@@ -18,6 +18,82 @@
  * what counts as a page are the half worth arguing over, and they can be argued
  * over offline. Fetching belongs to the caller.
  */
+/**
+ * RECORD-shaped kinds: individual entries in a catalogue this platform serves
+ * through ONE bound template plus real data, never as N static pages. Their
+ * words, checked FIRST — see `sitemapKind` below for why the order matters.
+ */
+const ENTITY_KIND_WORDS = [
+    ['product', ['product', 'products']],
+    ['category', ['category', 'categories']],
+    ['collection', ['collection', 'collections']],
+    ['brand', ['brand', 'brands']],
+    ['tag', ['tag', 'tags']],
+];
+/** PAGE-shaped kinds: ordinary content, one static page each. */
+const PAGE_KIND_WORDS = [
+    ['article', ['article', 'articles']],
+    ['post', ['post', 'posts']],
+    ['blog', ['blog', 'blogs']],
+    ['page', ['page', 'pages']],
+];
+/** The kinds `choosePages` excludes from a plan by default. */
+export const ENTITY_KINDS = new Set(ENTITY_KIND_WORDS.map(([k]) => k));
+/** How to name an entity kind's count in a sentence — "categories", not "categorys". */
+export const ENTITY_KIND_LABEL = {
+    product: 'products',
+    category: 'categories',
+    collection: 'collections',
+    brand: 'brands',
+    tag: 'tags',
+};
+/**
+ * What kind of `<loc>`s a child sitemap holds, read off its OWN FILENAME —
+ * never a guess about the URLs themselves. ttgshop.vn spells it
+ * `sitemap_product.xml`; Yoast writes `product-sitemap.xml`; Shopify numbers
+ * its shards `sitemap_products_1.xml`. All three are covered by testing
+ * whether the filename's own WORDS include one of the terms above.
+ *
+ * TOKENIZED, not a raw substring test. `"category"` as a plain substring can
+ * hit a coincidental run of letters inside an unrelated word (this repo has
+ * already paid once for exactly that mistake — `isPlumbing`'s boundary bug,
+ * above), and this catalog of kinds is short enough to name outright, so the
+ * filename is split on anything that is not a letter or digit and matched as
+ * whole TOKENS: a name has to actually SPELL "category" as its own word to
+ * read as one. A page sitemap never does.
+ *
+ * ENTITY words are checked before PAGE words. A filename naming both — a
+ * WordPress "blog categories" taxonomy archive, say — resolves to the
+ * entity: excluding a few thousand catalogue records is the safe direction
+ * to be wrong in, and importing them as static pages is the exact defect
+ * this function exists to prevent.
+ *
+ * A name with NEITHER — `sitemap.xml`, `sitemap1.xml`, `sitemap_index.xml` —
+ * returns `undefined`, which is what keeps every site shaped like that
+ * planning exactly as it always has.
+ */
+export function sitemapKind(sitemapUrl) {
+    let path;
+    try {
+        path = new URL(sitemapUrl).pathname;
+    }
+    catch {
+        path = sitemapUrl;
+    }
+    const file = path.split('/').filter(Boolean).pop() ?? '';
+    const tokens = new Set(file
+        .toLowerCase()
+        .replace(/\.xml(?:\.gz)?$/, '')
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean));
+    for (const [kind, words] of ENTITY_KIND_WORDS)
+        if (words.some((w) => tokens.has(w)))
+            return kind;
+    for (const [kind, words] of PAGE_KIND_WORDS)
+        if (words.some((w) => tokens.has(w)))
+            return kind;
+    return undefined;
+}
 /** Anything whose extension says it is a file rather than a page. */
 const ASSET = /\.(?:pdf|jpe?g|png|gif|webp|svg|ico|avif|css|js|mjs|json|xml|rss|atom|zip|rar|gz|tgz|tar|mp3|mp4|m4a|webm|mov|avi|woff2?|ttf|otf|eot|docx?|xlsx?|pptx?|csv|txt)$/i;
 /**
@@ -370,6 +446,7 @@ export function choosePages(entry, urls, opts = {}) {
     const exclude = (opts.exclude ?? []).map((s) => s.toLowerCase());
     const origin = originOf(entry);
     const skipped = {};
+    const kinds = {};
     const skip = (why) => {
         skipped[why] = (skipped[why] ?? 0) + 1;
     };
@@ -405,6 +482,16 @@ export function choosePages(entry, urls, opts = {}) {
         // about a stranger's site, and a caller who names `/account` knows something
         // this module does not.
         if (!wanted && norm !== entry) {
+            // RECORD-SHAPED KINDS ARE NOT PAGES HERE. Read off the sitemap that
+            // named it, never guessed at from the URL — see `sitemapKind`. A
+            // kindless `Found` (no child sitemap named it, or discovery fell
+            // through to the link crawl) is unaffected: this fires only when the
+            // site's own sitemap said so.
+            if (f.kind && ENTITY_KINDS.has(f.kind)) {
+                skip('entity-kind');
+                kinds[f.kind] = (kinds[f.kind] ?? 0) + 1;
+                continue;
+            }
             if (ASSET.test(path)) {
                 skip('asset');
                 continue;
@@ -441,7 +528,7 @@ export function choosePages(entry, urls, opts = {}) {
             continue;
         }
         seen.add(norm);
-        kept.push({ url: norm, from: norm === entry ? 'entry' : f.from });
+        kept.push({ url: norm, from: norm === entry ? 'entry' : f.from, ...(f.kind ? { kind: f.kind } : {}) });
     }
     const folded = foldLocales(kept, entry, skip);
     // GROUPS ARE COUNTED BEFORE THE CAP, because the whole point of reporting them
@@ -472,7 +559,7 @@ export function choosePages(entry, urls, opts = {}) {
         const slug = slugFor(f.url, taken);
         return { ...f, slug, name: nameFor(slug), depth: depthOf(f.url) };
     });
-    return { pages, skipped, groups };
+    return { pages, skipped, groups, kinds };
 }
 /**
  * The filter a link crawl needs, as one function: a raw href in, its canonical