sbuilder-mcp 0.7.2 → 0.9.0

package/CHANGELOG.md

@@ -6,6 +6,35 @@ 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.9.0] - 2026-09-08
+
+### Added
+- sb_set's `state` argument now accepts `"stuck"`, the look a pinned (`position: sticky` or `fixed`) element wears once the platform's runtime island marks it stuck, refusing the write when neither the node nor any ancestor can pin since the renderer would compile no rule for it and the override would be stored, published and never painted.
+- sb_set now seeds `top`/`zIndex` alongside a `position: sticky` write, matching what the platform's own editor seeds, since a pinned header with no z-index is painted over by later content the moment it scrolls past.
+- sb_set warns (in both dry_run and the real write) when a sticky node sits inside an ancestor whose overflow clips it, since sticky resolves against the nearest scrolling ancestor and a clipping one silently defeats the pin.
+- sb_review reports `stuck_no_host` for a `stuck` state override with no pinned self-or-ancestor, and `sticky_blocked` for a sticky node whose ancestor's overflow defeats it, so a document that reached either state through an import, a template, or a later edit is caught even when sb_set's own write-time checks were bypassed.
+- sb_import now carries a source section's `sticky`/`fixed` positioning onto the imported node, including the same offset and layer-order seeds sb_set writes, since a section pinned to stay in view is a layout decision distinct from one that scrolls away.
+
+### Fixed
+- sb_media_upload from a `url` no longer fails for every image and video type; the upload was sent with no declared content type, which the platform treats as neither an image nor a video, so it refused a plain PNG with a message that named the wrong cause. The source's own Content-Type header is used when it identifies the file, and the file extension otherwise.
+- sb_import no longer drops a link's text when the link wraps markup (such as `<a><span>Docs</span></a>`) whose contents produce nothing importable; it now keeps the link's own words instead of importing nothing for it.
+
+### Internal
+- The generated element catalog is refreshed against a current platform checkout: `dataset-block` and `list-dataset` now carry a content tip warning that a dataset node inside a repeater must bind to its own `config.datasetSource`, not the element's default.
+
+## [0.8.0] - 2026-09-08
+
+### Added
+- sb_add's `spec` argument now takes `responsive` on any node, seeding per-breakpoint style and config overrides at creation time instead of requiring a follow-up sb_set for every responsive value; it merges over the element's own seeded responsive defaults per namespace, so seeding a mobile style does not drop the element's own mobile config.
+- sb_import takes max_nodes (default 300), a single bound on the whole import; it replaces the old per-section cap, which silently became the real limit on a page whose body has one top-level child, and the amount skipped is now reported on a real run too, not only a dry one.
+- sb_import now preserves the source's layout: a container that actually lays its children out with flex or grid becomes a real row that stacks at mobile instead of every section flattening into one vertical column.
+
+### Fixed
+- sb_import now captures text from any element that holds it, not only `<p>` and `<blockquote>`, since most of the web does not use paragraph tags; a table-layout page or a utility-CSS page previously imported with none of its text at all.
+- sb_import's empty-result fallback now retries against the page's `<main>` whenever the sections it found produced no content, instead of only when it found no candidate sections in the first place.
+- sb_import now keeps an unpainted content link instead of dropping it, capturing it as a flat link-styled button rather than only capturing links that already look like a call to action; a painted button still requires a filled background or a border with actual width, so a Tailwind page's zero-width reset borders are no longer mistaken for one.
+- sb_import no longer imports the source page's own page-level header and footer, since the target page already carries its own as shared globals; a `<header>` nested inside a section (a hero) is still kept.
+
 ## [0.7.2] - 2026-09-08
 
 ### Fixed

package/CHANGELOG.vi.md

@@ -6,6 +6,35 @@ 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.9.0] - 2026-09-08
+
+### Added
+- Tham số `state` của sb_set giờ nhận `"stuck"`, trạng thái mà một phần tử được ghim (`position: sticky` hoặc `fixed`) mang khi runtime island của nền tảng đánh dấu nó là stuck; sb_set sẽ từ chối ghi khi không có node nào — bản thân node hay bất kỳ tổ tiên nào — có thể ghim được, vì khi đó renderer sẽ không biên dịch rule nào cả và override sẽ bị lưu, publish rồi không bao giờ được vẽ ra.
+- sb_set giờ tự gieo `top`/`zIndex` khi ghi `position: sticky`, khớp với những gì editor của chính nền tảng gieo sẵn, vì một header được ghim mà không có z-index sẽ bị nội dung phía sau vẽ đè lên ngay khi cuộn qua.
+- sb_set giờ cảnh báo (cả ở dry_run lẫn lần ghi thật) khi một node sticky nằm trong một tổ tiên có overflow cắt nó, vì sticky phân giải theo tổ tiên có thể cuộn gần nhất, và một tổ tiên cắt nội dung sẽ âm thầm vô hiệu hóa việc ghim.
+- sb_review giờ báo cáo `stuck_no_host` cho một override trạng thái `stuck` mà không có node ghim nào ở chính nó hay tổ tiên, và `sticky_blocked` cho một node sticky bị tổ tiên có overflow vô hiệu hóa, để một document đi đến một trong hai trạng thái này qua import, template, hoặc một chỉnh sửa sau đó vẫn bị phát hiện dù đã bỏ qua được các kiểm tra lúc ghi của sb_set.
+- sb_import giờ mang theo thuộc tính ghim `sticky`/`fixed` của một section nguồn sang node được import, kèm theo đúng các giá trị gieo về offset và thứ tự layer mà sb_set ghi, vì một section được ghim để luôn hiển thị là một quyết định bố cục khác với một section cuộn trôi đi.
+
+### Fixed
+- sb_media_upload từ `url` không còn thất bại với mọi loại ảnh và video; trước đây lần upload được gửi đi mà không khai báo content type, khiến nền tảng coi đó không phải ảnh cũng không phải video, nên nó từ chối cả một file PNG bình thường với thông báo nêu sai nguyên nhân. Giờ đây content-type khai báo của nguồn được dùng khi nó xác định đúng loại file, và phần mở rộng của tên file được dùng khi không xác định được.
+- sb_import không còn làm mất chữ của một liên kết khi liên kết đó bọc markup (như `<a><span>Docs</span></a>`) mà nội dung bên trong không import được gì; giờ nó giữ lại chính chữ của liên kết thay vì import ra không có gì cho nó.
+
+### Internal
+- Catalog element được tạo lại dựa trên một bản checkout hiện tại của nền tảng: `dataset-block` và `list-dataset` giờ mang một content tip cảnh báo rằng một node dataset bên trong repeater phải bind theo đúng `config.datasetSource` của chính nó, chứ không phải theo mặc định của element.
+
+## [0.8.0] - 2026-09-08
+
+### Added
+- Tham số `spec` của sb_add giờ nhận `responsive` trên bất kỳ node nào, cho phép gieo các override style và config theo từng breakpoint ngay lúc tạo node, thay vì phải gọi thêm sb_set cho mỗi giá trị responsive; nó merge đè lên các giá trị responsive mặc định mà chính element đã gieo sẵn theo từng namespace, nên việc gieo một style cho mobile sẽ không làm mất config mobile riêng của element.
+- sb_import nhận max_nodes (mặc định 300), một giới hạn duy nhất cho toàn bộ lần import; nó thay thế giới hạn theo từng section cũ, vốn âm thầm trở thành giới hạn thực tế trên một trang mà `<body>` chỉ có một phần tử con cấp cao nhất, và số lượng bị bỏ qua giờ được báo cáo cả ở lần chạy thật, không chỉ ở dry run.
+- sb_import giờ giữ lại cách bố trí của trang nguồn: một container thực sự sắp xếp các phần tử con bằng flex hoặc grid sẽ trở thành một row thật, tự động xếp chồng ở mobile, thay vì mọi section đều bị làm phẳng thành một cột dọc.
+
+### Fixed
+- sb_import giờ lấy text từ bất kỳ phần tử nào chứa nó, không chỉ `<p>` và `<blockquote>`, vì phần lớn nội dung trên web không dùng thẻ paragraph; một trang dùng layout bảng hoặc trang dùng utility-CSS trước đây bị import mà không lấy được chữ nào.
+- Cơ chế fallback khi không có kết quả của sb_import giờ thử lại với `<main>` của trang bất cứ khi nào các section tìm được không tạo ra nội dung nào, thay vì chỉ thử lại khi không tìm được section ứng viên nào ngay từ đầu.
+- sb_import giờ giữ lại một liên kết nội dung không được "tô" thay vì bỏ nó đi, lấy nó thành một button kiểu link phẳng thay vì chỉ lấy những liên kết đã trông giống một call-to-action; một button được "tô" vẫn cần có màu nền hoặc viền có độ dày thật, nên các viền reset độ dày bằng 0 của một trang dùng Tailwind không còn bị nhầm là một call-to-action nữa.
+- sb_import không còn import header và footer cấp trang của trang nguồn, vì trang đích đã có sẵn header/footer riêng dưới dạng global dùng chung; một `<header>` nằm lồng bên trong một section (dạng hero) vẫn được giữ lại.
+
 ## [0.7.2] - 2026-09-08
 
 ### Fixed

package/dist/catalog/elements.generated.js

@@ -30090,7 +30090,9 @@ export const ELEMENTS = {
             "Place it on a product or collection page so its children inherit that page binding automatically; on any OTHER page, pin a standalone product via the Product trait group (and optionally a default variant) so the children preview that product",
             "Fill it with dataset children (media-dataset, text-dataset, pricing-dataset, product-variants, quantity, buttons); style each field on its own node",
             "Use direction + gap for the internal flex layout and content-width to cap and center the card",
-            "Prefer a horizontal split (media beside a content column) for buy boxes and a vertical stack for compact cards"
+            "Prefer a horizontal split (media beside a content column) for buy boxes and a vertical stack for compact cards",
+            "config.datasetSource names the ENTITY this card holds — \"product\" (the default when the key is absent), \"category\", \"article\", \"blogCategory\", \"course\" or \"review\". Inside a list-dataset it MUST equal the repeater's own datasetSource: it is what makes the card bind that entity's fields AND what gives the card its link, so a collection card left on the default binds product.url, resolves to nothing in a collection row, and publishes with no link on it at all",
+            "Set the same datasetSource on every dataset child of the card (text-dataset, collection-media) — each child reads its own key, not the card's"
         ],
         "semantics": [
             "dataset",
@@ -31465,6 +31467,7 @@ export const ELEMENTS = {
         ],
         "contentTips": [
             "Always add exactly one dataset-block child as the repeated item template; every row clones that exact structure and styling",
+            "The dataset-block template — and every dataset node inside it — must carry the SAME config.datasetSource as this repeater. Each node reads its OWN key, so a collection list whose card omits it leaves that card on the product default: it binds product.url, no product context reaches a collection row, and the card publishes with no link, so clicking it does nothing",
             "config.datasetSource picks the ENTITY: \"product\" for a product list, \"category\" for a collection list. It is what derives the node's binding target (product::product_list / category::collection_list)",
             "Product lists: config.collectionType \"all_products\" renders the whole catalog, \"collection\" renders the one named by config.collectionId, \"related\" renders the PAGE PRODUCT's neighbours — the products sharing one of its collections, minus itself",
             "Use \"related\" for a cross-sell shelf on a product page (\"Sản phẩm liên quan\" / \"You may also like\"). It reads no collectionId — its axis is whatever collections the page product is filed under — and it renders nothing on a page that names no product, so pair it with an emptyStateId if the section must never be blank",

package/dist/domains/site/builder.js

@@ -2,6 +2,7 @@ import { isOverlay, subtreeIds, ancestors, appBlockRoot, SPEC_GLOBAL_ID, SPEC_GL
 import { ELEMENTS, ELEMENT_SEEDS, SATELLITE_RULES } from '../../catalog/elements.generated.js';
 import { bindingsForConfig, createNode, mintSatellites } from './node.js';
 import { refuseSecondTemplate } from './traps.js';
+import { STUCK_STATE, refuseStuckConfig, requireStuckHost, stickySeeds } from './sticky.js';
 import { genId } from './ids.js';
 /** Append sentinel: splice clamps a too-large index, and `isSyncablePatch`
  *  deliberately allows one — an append is a legitimate thing to describe. */
@@ -90,6 +91,7 @@ export function addSubtree(doc, parentId, spec, index) {
             style: s.style,
             config: s.config,
             specials: s.specials,
+            responsive: s.responsive,
         });
         // Before the owner is handed to a patch: minting rewrites its `config`.
         const sats = mintSatellites(n);
@@ -203,6 +205,16 @@ export function setKeys(doc, id, keys, opts) {
     // documents that exact call — `sb_set pr_option style base:true state:"active"`
     // — as the way to style a selected option.
     if (opts.state) {
+        // THE STUCK STATE IS THE ONE STATE WITH A PRECONDITION. Every other state
+        // is a pseudo-class the browser resolves on the node itself; `stuck` is a
+        // class a runtime island toggles on the PINNED element, and the renderer
+        // emits no rule at all when there is nothing pinned to hang it off. See
+        // sticky.ts — this is the whole reason that module exists.
+        if (opts.state === STUCK_STATE) {
+            requireStuckHost(doc.doc, id);
+            if (namespace === 'config')
+                refuseStuckConfig(keys);
+        }
         // Base state and per-breakpoint state are DIFFERENT PLACES in the document,
         // and the old path (`states[state][bp][ns]`) was neither of them: it buried
         // a breakpoint inside the base-state cluster, where nothing reads it.
@@ -218,6 +230,15 @@ export function setKeys(doc, id, keys, opts) {
             ...(rebind ? [rebind] : []),
         ];
     }
+    // WRITING `position: sticky` IS THREE WRITES, and the editor makes all three.
+    // An agent that made only the first shipped a header the page paints over —
+    // measured in Chromium by the platform, not inferred. Seeded only where the
+    // caller and the node are both silent, so an explicit answer always wins.
+    if (namespace === 'style') {
+        const seeds = stickySeeds(doc.node(id), keys, opts.base ? undefined : (opts.breakpoint ?? 'desktop'));
+        if (Object.keys(seeds).length)
+            keys = { ...seeds, ...keys };
+    }
     if (opts.base) {
         // Base IS legitimate, and this used to throw for anything that was not an
         // identity key — a refusal built on a misread of the platform's responsive

package/dist/domains/site/findings.js

@@ -54,6 +54,16 @@ export const FIX = {
     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" }.',
     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.
+    sticky_blocked: 'Clear the clip on the ancestor: sb_set id "<key>", namespace style, keys ' +
+        '{ "overflowX": "visible", "overflowY": "visible" } — or move the pinned node outside it. ' +
+        'Sticky resolves against its nearest SCROLLING ancestor, so a clipping one becomes that ' +
+        'ancestor and the node pins inside a box that never scrolls.',
+    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, ' +
+        'published and never painted. To drop it instead, remove the stuck slot.',
 };
 /** The template for `code`, with every `<name>` in `vars` substituted. */
 export function fill(code, vars) {

package/dist/domains/site/importmap.js

@@ -1,4 +1,5 @@
 import { walk } from '../../core/tree.js';
+import { stickySeeds } from './sticky.js';
 /** Style keys read off a node, ignoring anything unset. */
 function styleOf(n) {
     return (n?.style ?? {});
@@ -125,6 +126,26 @@ function one(c, t) {
             const text = c.text?.trim();
             if (!text)
                 return null;
+            // TWO KINDS OF LINK, and giving them one look was wrong in both
+            // directions. Painting every link produced 38 pink pills out of a
+            // documentation sidebar; dropping the unpainted ones lost a whole page of
+            // story titles. A call to action takes the target's FILL; a link takes its
+            // accent as INK and nothing else, which is the platform's own idiom for a
+            // link (a button carrying href, styled flat).
+            if (c.variant === 'link') {
+                return {
+                    type: 'button',
+                    specials: { text, ...(c.href ? { href: c.href } : {}) },
+                    style: {
+                        width: 'fit-content',
+                        backgroundColor: 'transparent',
+                        border: 'none',
+                        padding: '0',
+                        fontWeight: '500',
+                        ...(t.buttonBg ? { color: t.buttonBg } : {}),
+                    },
+                };
+            }
             return {
                 type: 'button',
                 specials: { text, ...(c.href ? { href: c.href } : {}) },
@@ -157,6 +178,40 @@ function one(c, t) {
                 })),
             };
         }
+        case 'group': {
+            const kids = (c.children ?? []).map((k) => one(k, t)).filter((n) => n !== null);
+            if (kids.length === 0)
+                return null;
+            if (kids.length === 1)
+                return kids[0];
+            // A ROW OF TWO OR MORE COLUMNS NEEDS AN EXPLICIT STACK BREAKPOINT, and
+            // nothing catches it for you: the columns SHRINK to fit, so no box
+            // overflows and `measure` stays silent while a photo becomes a sliver and
+            // a label truncates mid-word. Rule 3 of the design skill, and an import is
+            // the one place a row arrives without anybody having thought about 390.
+            //
+            // The wide answer is said out loud at base too, because the cascade
+            // resolves narrower slots LAST but does consult them: a `column` written
+            // only at mobile would otherwise reach desktop whenever base declares
+            // nothing.
+            return {
+                type: 'flex-block',
+                style: {
+                    width: '100%',
+                    display: 'flex',
+                    flexDirection: 'row',
+                    flexWrap: c.wrap ? 'wrap' : 'nowrap',
+                    alignItems: 'flex-start',
+                    gap: '24px',
+                },
+                responsive: { mobile: { style: { flexDirection: 'column', gap: '16px' } } },
+                children: kids.map((k) => ({
+                    type: 'flex-block',
+                    style: { flex: '1 1 280px', minWidth: '0', display: 'flex', flexDirection: 'column', gap: '12px' },
+                    children: [k],
+                })),
+            };
+        }
         case 'section': {
             const kids = (c.children ?? []).map((k) => one(k, t)).filter((n) => n !== null);
             if (kids.length === 0)
@@ -165,6 +220,20 @@ function one(c, t) {
             // inner block is what carries the page's own measure — an imported band
             // that runs the full window width on a page whose sections are 1200 reads
             // as a different site even when every colour matches.
+            // A PINNED SECTION ARRIVES WITH ALL THREE KEYS, never just `position`.
+            // The offset and the layer order are not decoration: measured in Chromium
+            // by the platform, a pinned section with no z-index is painted OVER by any
+            // `position: relative` element in a later section the moment it scrolls
+            // past, which reads as the import having produced a broken band rather
+            // than as a stacking question nobody answered. `stickySeeds` is the one
+            // place that says what they are, so this cannot drift from `sb_set`.
+            //
+            // `fixed` is carried as the source declared it, seeds and all — a fixed
+            // bar with no offset would sit wherever the flow left it, which on an
+            // imported page is not where the source had it.
+            const pin = c.pinned
+                ? { position: c.pinned, ...stickySeeds(undefined, { position: 'sticky' }) }
+                : {};
             return {
                 type: 'flex-section',
                 style: {
@@ -173,6 +242,7 @@ function one(c, t) {
                     flexDirection: 'column',
                     alignItems: 'center',
                     ...(t.sectionPadding ? { padding: t.sectionPadding } : { padding: '64px 24px' }),
+                    ...pin,
                 },
                 children: [
                     {

package/dist/domains/site/node.js

@@ -1,5 +1,26 @@
 import { ELEMENTS, SATELLITE_RULES } from '../../catalog/elements.generated.js';
 import { genId } from './ids.js';
+/**
+ * The element's own per-breakpoint defaults with the caller's laid over them.
+ *
+ * Per NAMESPACE, not per slot: an element that seeds `mobile.config.iconSize`
+ * and a caller who asks for `mobile.style.flexDirection` must end with both.
+ * Replacing the slot would drop the one nobody mentioned, which is the quiet
+ * kind of loss this repo keeps finding.
+ */
+function mergeResponsive(base, over) {
+    if (!over)
+        return base;
+    const out = { ...base };
+    for (const [bp, slot] of Object.entries(over)) {
+        out[bp] = {
+            ...(out[bp] ?? {}),
+            ...(slot.style ? { style: { ...(out[bp]?.style ?? {}), ...slot.style } } : {}),
+            ...(slot.config ? { config: { ...(out[bp]?.config ?? {}), ...slot.config } } : {}),
+        };
+    }
+    return out;
+}
 /** Structured clone via JSON — the defaults are plain data, and this is what
  *  stops two nodes of the same type sharing one nested object. */
 function copy(v) {
@@ -73,7 +94,7 @@ export function createNode(type, opts = {}) {
         style: { ...copy(d.style ?? {}), ...(opts.style ?? {}) },
         config,
         specials: { ...copy(d.specials ?? {}), ...(opts.specials ?? {}) },
-        responsive: copy(d.responsive ?? {}),
+        responsive: mergeResponsive(copy(d.responsive ?? {}), opts.responsive),
         ...(states ? { states: copy(states) } : {}),
         events: [],
         // SEED THE ELEMENT'S OWN BINDINGS.

package/dist/domains/site/review.js

@@ -1,4 +1,5 @@
 import { childrenOf, childrenWithSatellites, isOverlay, pageChildren, appBlockRoot, SPEC_GLOBAL_REF, SPEC_APP_BLOCK_REF } from '../../core/tree.js';
+import { STUCK_STATE, stickyBlockedBy, stuckHostOf, isPinnedNode } from './sticky.js';
 import { ELEMENTS, BINDING_SOURCES, BOUND_SPECIALS, FIRST_CHILD_ONLY, SATELLITE_RULES, ELEMENT_SEEDS } from '../../catalog/elements.generated.js';
 import { fill } from './findings.js';
 /**
@@ -188,6 +189,44 @@ export function reviewDesign(doc) {
             });
             continue;
         }
+        // PINNING FAILS WITH NOTHING ON SCREEN AND NOTHING IN THE LOG — both halves
+        // of it — which is exactly what a review is for. `sb_set` refuses the second
+        // case at write time, but a document reaches here by other roads: an import,
+        // a template, or a later edit that un-pinned the host and left the overrides
+        // behind.
+        const styled = n;
+        if (isPinnedNode(n)) {
+            const blocker = stickyBlockedBy(d, id);
+            // Sticky only: a `fixed` element is positioned against the viewport and an
+            // overflow ancestor cannot take that away from it.
+            const sticky = String(styled.style?.position) === 'sticky' ||
+                Object.values(styled.responsive ?? {}).some((r) => String(r?.style?.position) === 'sticky');
+            if (blocker && sticky) {
+                out.push({
+                    code: 'sticky_blocked',
+                    nodeId: id,
+                    type,
+                    problem: `Pinned, but ancestor "${blocker}" clips its overflow — so that ancestor becomes ` +
+                        'the scroll container this node pins inside, and it never scrolls. The node does ' +
+                        'not move, and nothing reports it.',
+                    key: blocker,
+                    fix: fill('sticky_blocked', { id, key: blocker }),
+                });
+            }
+        }
+        const hasStuck = styled.states?.[STUCK_STATE] !== undefined ||
+            Object.values(styled.responsive ?? {}).some((r) => r?.states?.[STUCK_STATE] !== undefined);
+        if (hasStuck && !stuckHostOf(d, id)) {
+            out.push({
+                code: 'stuck_no_host',
+                nodeId: id,
+                type,
+                problem: 'Carries a "stuck" override, but neither it nor any ancestor can pin — so the ' +
+                    'renderer emits no rule for it. The styling is stored, saved and published, and ' +
+                    'never painted.',
+                fix: fill('stuck_no_host', { id }),
+            });
+        }
         const bindings = n.bindings ?? [];
         // A container with nothing in it is a band of empty space. The commonest way
         // to ship one is to add the section and then get distracted.

package/dist/domains/site/sticky.js

@@ -0,0 +1,208 @@
+import { ancestors } from '../../core/tree.js';
+/**
+ * PINNING, AND THE STATE A PINNED ELEMENT WEARS ONCE IT IS STUCK.
+ *
+ * The platform gained this in September 2026 (`schema/src/stickyState.ts`, Go
+ * mirror `server/render/style/sticky.go`), and every part of it fails SILENTLY
+ * when authored wrong — which is why it needs a module here rather than a note.
+ *
+ * `position: sticky` changes nothing observable when it engages: CSS has no
+ * `:stuck` pseudo-class. So the platform toggles ONE class (`wb-stuck`) on the
+ * pinned element from a runtime island, and compiles every rule an author wrote
+ * for the pinned look against it — the node itself as `#self.wb-stuck`, a
+ * DESCENDANT as `#host.wb-stuck #self`, which is what lets a pinned header
+ * shrink its logo without the logo knowing what pinned it.
+ *
+ * Three things about it are load-bearing here, and each is a write that
+ * disappears without one:
+ *
+ *   1. THE STATE NEEDS A HOST. `render/css.go` emits the stuck rules inside
+ *      `if stuckHost := stuckHostFor(...); stuckHost != ""`. A `stuck` override
+ *      on a node with no pinned self-or-ancestor compiles to NOTHING — stored,
+ *      saved, published and ignored forever, the same shape as a binding in a
+ *      namespace `applyBindings` does not honour.
+ *   2. THE SEEDS ARE NOT COSMETIC. The editor writes `top: 0px` and
+ *      `zIndex: 10` the moment an author picks "Stick on scroll", and the
+ *      platform's own commit records why the second one exists: measured in
+ *      Chromium, a pinned header with no z-index is painted OVER by any
+ *      `position: relative` element in a later section the moment it scrolls
+ *      past. An agent writing `position: sticky` through `sb_set` reaches none
+ *      of that, so its first sticky header half-works in the way that reads as
+ *      the feature being broken.
+ *   3. A CLIPPING ANCESTOR DEFEATS IT ENTIRELY. Sticky resolves against its
+ *      nearest SCROLLING ancestor, so an ancestor with `overflow: hidden|auto|
+ *      scroll|clip|overlay` becomes that ancestor and the node pins inside a box
+ *      that never scrolls. Nothing on screen and nothing in the log explains it.
+ */
+/** The state key, in `node.states` and `responsive[bp].states`. */
+export const STUCK_STATE = 'stuck';
+/**
+ * The positions that HAVE a pinned moment.
+ *
+ * `fixed` earns its place for a different reason than `sticky`: it is pinned
+ * from the first frame, so "the moment it pins" never happens to it — but "the
+ * moment the page has scrolled past where it would have been" does, and that is
+ * the same design an author reaches for (the fixed header that goes opaque once
+ * the hero is behind it). `absolute` is deliberately absent: it scrolls away
+ * with the page, so it has no relationship to the scroll position at all.
+ */
+const PINNED_POSITIONS = new Set(['sticky', 'fixed']);
+/**
+ * Overflow values that make an ancestor a scroll container — an ALLOWLIST of
+ * the clipping ones, not `!== 'visible'`, so an unknown or misspelled value
+ * never produces a warning nobody can act on. Mirrors the editor's
+ * `dnd/stickyBlockers.ts`.
+ */
+const CLIPPING = new Set(['hidden', 'auto', 'scroll', 'clip', 'overlay']);
+const BREAKPOINTS = ['desktop', 'laptop', 'tablet', 'mobile'];
+function styleAt(node, bp) {
+    if (!node)
+        return {};
+    return (bp ? node.responsive?.[bp]?.style : node.style) ?? {};
+}
+/**
+ * Does any slot on this node ask for a position that can pin?
+ *
+ * Breakpoint-agnostic on purpose, exactly as the platform's `isPinnedNode` is: a
+ * header pinned only on desktop still compiles its stuck rules at every width —
+ * they simply never match, because the class only appears while the element is
+ * genuinely stuck, which the island re-decides per viewport.
+ */
+export function isPinnedNode(node) {
+    if (!node)
+        return false;
+    if (PINNED_POSITIONS.has(String(styleAt(node).position)))
+        return true;
+    return BREAKPOINTS.some((bp) => PINNED_POSITIONS.has(String(styleAt(node, bp).position)));
+}
+/**
+ * The pinned self-or-ancestor whose `wb-stuck` class this node's stuck rules
+ * would key off, or null. Nearest wins; a pinned node answers with itself.
+ */
+export function stuckHostOf(doc, id) {
+    if (isPinnedNode(doc.nodes[id]))
+        return id;
+    for (const up of ancestors(doc, id)) {
+        if (isPinnedNode(doc.nodes[up]))
+            return up;
+    }
+    return null;
+}
+/**
+ * The nearest ancestor whose overflow stops a sticky node from working, or null.
+ *
+ * Starts at the PARENT: a sticky element's own overflow clips its children, not
+ * itself, and blaming it would send the caller to fix a property that is not the
+ * problem. Reads base overlaid with `bp` — the cascade's own order for a single
+ * key — so a clip declared only at mobile is named only when writing mobile.
+ */
+export function stickyBlockedBy(doc, id, bp) {
+    for (const up of ancestors(doc, id)) {
+        const node = doc.nodes[up];
+        if (!node)
+            return null;
+        const s = { ...styleAt(node), ...(bp ? styleAt(node, bp) : {}) };
+        if (CLIPPING.has(String(s.overflowX)) || CLIPPING.has(String(s.overflowY)))
+            return up;
+    }
+    return null;
+}
+/**
+ * The keys the editor writes alongside `position: sticky`, for the same reasons
+ * — offered here only when the caller has not answered them and the node does
+ * not already, so an explicit choice is never overwritten.
+ *
+ * `top` is skipped when the same call pins to another edge: the inspector writes
+ * one key at a time and cannot have that case, an agent writing
+ * `{ position: 'sticky', bottom: '0px' }` in one object plainly can, and seeding
+ * `top: 0` over it would pin a bottom bar to the ceiling.
+ *
+ * `10` for the layer order is a specific number, not a large one: it sits above
+ * ordinary page content and BELOW the overlay ladder the static CSS owns (cart
+ * scrim 40, drawer 41, pop-up scrim 50, pop-up 51). A header that outranked
+ * those would cover the drawer it opens.
+ */
+export function stickySeeds(node, keys, bp) {
+    if (String(keys.position) !== 'sticky')
+        return {};
+    const merged = { ...styleAt(node), ...(bp ? styleAt(node, bp) : {}), ...keys };
+    const seeds = {};
+    if (merged.top === undefined && merged.bottom === undefined)
+        seeds.top = '0px';
+    if (merged.zIndex === undefined)
+        seeds.zIndex = '10';
+    return seeds;
+}
+/**
+ * What a stuck state may carry in `config`.
+ *
+ * `stuckDecls` reads the style slot whole and translates exactly ONE config key
+ * — `hidden` — into `display: none`, because a state has no bands and no cascade
+ * of its own, so a declaration is the only shape available. Every other config
+ * key in a stuck slot is stored by the document and read by no compiler.
+ *
+ * And only `true` is honoured: `false` would have to mean "show it again while
+ * pinned", which needs `display: revert`, and the platform's `render/css.go`
+ * documents at length why revert is wrong here — it rolls the property back past
+ * the element's own static CSS and lands on the UA default. So OFF means "no
+ * override", i.e. remove the key.
+ */
+export function refuseStuckConfig(keys) {
+    const stray = Object.keys(keys).filter((k) => k !== 'hidden');
+    if (stray.length) {
+        throw new Error(`sbuilder: the stuck state translates exactly one config key — "hidden" — into a ` +
+            `declaration (display:none). ${stray.map((k) => `"${k}"`).join(', ')} would be stored ` +
+            'and read by no compiler. A state has no bands and no cascade, so style is what it ' +
+            'paints: write these in the style namespace, or at base if they are not stuck-specific.');
+    }
+    if ('hidden' in keys && keys.hidden !== true) {
+        throw new Error('sbuilder: stuck config.hidden takes only true. false would have to mean "show it again ' +
+            'while pinned", which needs display:revert — wrong here, because revert rolls past the ' +
+            "element's own static CSS to the UA default. To stop hiding it, remove the override.");
+    }
+}
+/**
+ * Refuse a stuck override that no selector would ever match.
+ *
+ * The message names the fix rather than the rule, because the caller who lands
+ * here is one step from the design they wanted: pin this node, or pin the
+ * section it lives in, and the same override starts painting.
+ */
+export function requireStuckHost(doc, id) {
+    if (stuckHostOf(doc, id))
+        return;
+    const up = ancestors(doc, id)[0];
+    throw new Error(`sbuilder: "${STUCK_STATE}" is the state a PINNED element wears once it is stuck, and ` +
+        `neither ${id} nor any ancestor can pin — so the platform compiles no rule for it ` +
+        '(render/css.go emits stuck CSS only under a stuck host). The override would be stored, ' +
+        'saved, published and never painted. Pin the element that scrolls first: ' +
+        `sb_set ${up ?? id} style { position: "sticky" } — a descendant then styles itself ` +
+        'through the host, so this node needs no position of its own.');
+}
+/**
+ * The warning a sticky node earns when an ancestor's overflow will defeat it.
+ *
+ * Only for `sticky`. A `fixed` element is positioned against the viewport and
+ * an overflow ancestor cannot take that away from it — the ancestors that CAN
+ * (a `transform`, a `filter`, a `contain`) are a different question this does
+ * not pretend to answer.
+ *
+ * A warning rather than a refusal, because the clip may be the deliberate half:
+ * the author may be about to remove it, or may mean the node to pin inside a
+ * scrolling panel. Silence is the only wrong answer — the failure shows up as
+ * nothing on screen and nothing in the log.
+ */
+export function stickyWarning(doc, id, bp) {
+    const node = doc.nodes[id];
+    const sticky = String(styleAt(node).position) === 'sticky' ||
+        BREAKPOINTS.some((b) => String(styleAt(node, b).position) === 'sticky');
+    if (!sticky)
+        return null;
+    const blocker = stickyBlockedBy(doc, id, bp);
+    if (!blocker)
+        return null;
+    return (`${id} is sticky, but ancestor ${blocker} clips its overflow (hidden/auto/scroll/clip/` +
+        'overlay), so it becomes the scroll container this node pins inside — a box that never ' +
+        `scrolls. The node will not move. Clear overflowX/overflowY on ${blocker}, or pin a node ` +
+        'outside it.');
+}

package/dist/tools/importpage.js

@@ -41,6 +41,13 @@ export function registerImportTools(server, ctx, session) {
                 .max(100)
                 .optional()
                 .describe('Default 24 — every image is an upload'),
+            max_nodes: z
+                .number()
+                .int()
+                .min(1)
+                .max(1000)
+                .optional()
+                .describe('Default 300 — the bound on the whole import'),
             upload_images: z
                 .boolean()
                 .optional()
@@ -48,13 +55,17 @@ export function registerImportTools(server, ctx, session) {
             dry_run: z.boolean().optional(),
         },
         annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
-    }, async ({ url, site_id: given, max_sections, max_images, upload_images, dry_run }) => {
+    }, async ({ url, site_id: given, max_sections, max_images, max_nodes, upload_images, dry_run }) => {
         const siteId = siteFor(ctx, given);
         // THE TARGET PAGE MUST BE OPEN, and not only because that is where the
         // nodes go: its own heading, button and section are where the tokens come
         // from, so an import with no open page is an import with no design.
         const doc = session.current();
-        const shot = await capture(url, { maxSections: max_sections, maxImages: max_images });
+        const shot = await capture(url, {
+            maxSections: max_sections,
+            maxImages: max_images,
+            maxNodes: max_nodes,
+        });
         const tokens = tokensFromPage(doc.doc);
         const images = imageSources(shot.sections);
         if (dry_run !== false) {
@@ -78,11 +89,16 @@ export function registerImportTools(server, ctx, session) {
         const rehosted = new Map();
         // WHY it failed, not just how many. Four images refused for the same
         // reason is ONE thing to fix, and a bare count is the shape that sends a
-        // caller to re-run the import hoping for a different answer. Measured: a
-        // real import lost all four images to `only image, video, or font
-        // (woff2/woff/ttf/otf) uploads are supported` — the platform refusing SVG,
-        // whose own sentinel exists precisely so a caller can be told "convert it
-        // first". The count alone said none of that.
+        // caller to re-run the import hoping for a different answer.
+        //
+        // The measurement that proved it worth having also proved a CONCLUSION
+        // WRONG. A real import lost all four images to `only image, video, or font
+        // (woff2/woff/ttf/otf) uploads are supported`, and that was written up here
+        // as the platform refusing SVG. It does not refuse SVG: it accepts any
+        // declared `image/*`, and `image/svg+xml` is one. `uploadMedia` was sending
+        // a typeless Blob, so EVERY url upload arrived as `application/octet-stream`
+        // — a PNG was refused by the same message. A reason carried verbatim is
+        // what makes a wrong reading of it findable.
         const failures = new Map();
         if (upload_images !== false) {
             for (const src of images) {
@@ -115,6 +131,11 @@ export function registerImportTools(server, ctx, session) {
         return text({
             read: shot.url,
             added_sections: added,
+            // WHAT WAS LEFT BEHIND, on the real run too. The dry run said it and the
+            // real one did not, which is the wrong way round: a caller who skipped
+            // the preview is exactly the caller who needs to be told that 21 nodes
+            // hit the ceiling, or that the page's own header was dropped on purpose.
+            ...(Object.keys(shot.skipped).length ? { skipped: shot.skipped } : {}),
             images: {
                 copied: rehosted.size,
                 ...(failed.length ? { failed } : {}),

package/dist/tools/page.js

@@ -13,6 +13,8 @@ import { readinessGaps, READINESS_NOTICE } from '../domains/site/readiness.js';
 import { gatherReadiness } from '../domains/site/readiness-fetch.js';
 import { globalWarning, restampPatches, RESPONSIVE_NOTICE } from '../domains/site/traps.js';
 import { catalogMatches, traitsFor } from '../catalog/element-search.js';
+import { applyPatches } from '../core/patch.js';
+import { stickyWarning } from '../domains/site/sticky.js';
 import { siteFor } from './context.js';
 import { projectList, PAGE_FIELDS, TEMPLATE_FIELDS } from './project.js';
 /**
@@ -262,7 +264,12 @@ export function registerPageTools(server, ctx) {
             keys: z.record(z.unknown()).optional(),
             breakpoint: z.enum(['desktop', 'laptop', 'tablet', 'mobile']).optional(),
             base: z.boolean().optional(),
-            state: z.string().optional().describe('An interaction state, e.g. "hover"'),
+            state: z
+                .string()
+                .optional()
+                .describe('An interaction state — "hover", or "stuck" for how a pinned element looks once ' +
+                'it is stuck (needs a sticky/fixed self-or-ancestor; a descendant styles itself ' +
+                'through the host).'),
             edits: z
                 .array(z.object({
                 id: z.string(),
@@ -287,17 +294,46 @@ export function registerPageTools(server, ctx) {
             batch.push({ id, namespace, keys, breakpoint: breakpoint, base, state });
         }
         const { patches, touched } = setMany(d, batch);
+        // THE STICKY WARNING IS COMPUTED AGAINST THE DOCUMENT AS IT WILL BE, so
+        // the dry run and the real run say the same thing. A caller who is told
+        // only after committing has already shipped a header that does not move.
+        const stuck = () => {
+            // Gated on the batch actually being able to change the answer, because
+            // a page document is hundreds of KB and sb_set is the hottest write
+            // there is: a clone on every call would tax every edit for a warning
+            // that fires on almost none. `position` and `overflow*` are the only
+            // two keys in the question.
+            const relevant = batch.some((e) => e.namespace === 'style' &&
+                ('position' in e.keys || 'overflowX' in e.keys || 'overflowY' in e.keys));
+            const out = {};
+            if (!relevant)
+                return out;
+            const probe = JSON.parse(JSON.stringify(d.doc));
+            applyPatches(probe, patches);
+            for (const e of batch) {
+                const w = stickyWarning(probe, e.id, e.base ? undefined : (e.breakpoint ?? 'desktop'));
+                if (w)
+                    out[e.id] = w;
+            }
+            return out;
+        };
         if (dry_run !== false) {
             const note = ctx.notices.once('responsive', RESPONSIVE_NOTICE);
-            return text({ dry_run: true, patches, ...(note ? { note } : {}) });
+            const sw = stuck();
+            return text({
+                dry_run: true,
+                patches,
+                ...(Object.keys(sw).length ? { warnings: sw } : {}),
+                ...(note ? { note } : {}),
+            });
         }
+        const warnings = stuck();
         session.applyAndPublish(patches);
         await session.save();
-        const warnings = {};
         for (const t of touched) {
             const w = globalWarning(d.doc, t.id);
             if (w)
-                warnings[t.id] = w;
+                warnings[t.id] = warnings[t.id] ? `${warnings[t.id]} ${w}` : w;
         }
         if (!edits) {
             const warn = warnings[batch[0].id];

package/dist/transport/media.js

@@ -15,10 +15,37 @@ import { siteToken } from '../tools/credentialpick.js';
  *
  * Node ≥22 has FormData, Blob and fetch as globals, so this needs no dependency.
  */
+/**
+ * A content type from the file NAME, for the local-path case and as the fallback
+ * when a server answers with nothing useful.
+ *
+ * Deliberately small: the platform decides what it accepts, and duplicating its
+ * whole table here would be a second place for that policy to drift. These are
+ * the types a page actually carries.
+ */
+const TYPE_BY_EXT = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.bmp': 'image/bmp',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.mov': 'video/quicktime',
+};
+function typeForName(name) {
+    const dot = name.lastIndexOf('.');
+    return dot < 0 ? '' : (TYPE_BY_EXT[name.slice(dot).toLowerCase()] ?? '');
+}
 export async function uploadMedia(ctx, siteId, source) {
     const doFetch = ctx.fetchImpl ?? fetch;
     let bytes;
     let filename;
+    let declared = '';
     if (source.path) {
         bytes = await readFile(source.path);
         filename = source.name ?? basename(source.path);
@@ -29,6 +56,8 @@ export async function uploadMedia(ctx, siteId, source) {
             throw new ApiError(res.status, 'source_unreachable', `could not fetch ${source.url}`);
         }
         bytes = new Uint8Array(await res.arrayBuffer());
+        // The SOURCE'S OWN answer first — it is the only party that actually knows.
+        declared = (res.headers.get('content-type') ?? '').split(';')[0].trim();
         // A URL's last segment is usually the filename; when it is not (a query-only
         // CDN link), name it rather than uploading something called "".
         filename = source.name ?? (new URL(source.url).pathname.split('/').pop() || 'image');
@@ -36,8 +65,25 @@ export async function uploadMedia(ctx, siteId, source) {
     else {
         throw new Error('sbuilder: give sb_media_upload either a local path or a url');
     }
+    // THE HEADER ONLY WINS WHEN IT SAYS SOMETHING. A CDN answering
+    // `application/octet-stream` for a PNG is ordinary, and it is exactly the
+    // value the platform refuses — so "the server declared a type" is not the
+    // question; "the server declared a type that identifies the file" is.
+    const usable = declared.startsWith('image/') || declared.startsWith('video/');
+    const type = (usable ? declared : '') || typeForName(filename) || declared;
     const form = new FormData();
-    form.set('file', new Blob([bytes]), filename);
+    // THE BLOB'S TYPE IS THE UPLOAD'S CONTENT TYPE, and omitting it broke every
+    // upload this function ever made from a URL. A typeless Blob is sent as
+    // `application/octet-stream`, the platform accepts a file whose declared type
+    // starts with `image/` or `video/` (or whose EXTENSION is a known font or
+    // document), and octet-stream is none of those — so a PNG fetched from a URL
+    // was refused with "only image, video, or font uploads are supported", which
+    // reads as a policy about the FILE and is really a bug in this line.
+    //
+    // It cost a wrong conclusion too: the same refusal on an SVG was written up
+    // here as "the platform deliberately refuses SVG". It does not — it accepts
+    // any `image/*`, and `image/svg+xml` is one.
+    form.set('file', new Blob([bytes], type ? { type } : undefined), filename);
     if (source.name)
         form.set('name', source.name);
     if (source.folderId)

package/dist/vision/capture.js

@@ -13,7 +13,7 @@ function capturePage(limits) {
     // page, as `ReferenceError: HEADINGS is not defined`, by which point the file
     // already carried a comment saying exactly that.
     const HEADINGS = new Set(['H1', 'H2', 'H3', 'H4', 'H5', 'H6']);
-    const taken = { images: 0 };
+    const taken = { images: 0, nodes: 0 };
     const skipped = {};
     const skip = (why) => void (skipped[why] = (skipped[why] ?? 0) + 1);
     const here = location.href;
@@ -67,73 +67,164 @@ function capturePage(limits) {
         'SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE', 'SVG', 'PATH', 'IFRAME', 'CANVAS',
         'NAV', 'FORM', 'INPUT', 'SELECT', 'TEXTAREA', 'BUTTON',
     ]);
-    /** Collect the renderable leaves under one section, in document order. */
+    /**
+     * The renderable content under one section, AS A TREE.
+     *
+     * It used to return a flat list, and flatness was the biggest thing an import
+     * lost. A source's three-column feature row came back as three stacked blocks;
+     * a card — image, heading, copy, button — came back as four siblings with
+     * nothing saying they belonged together. Everything a reader understands from
+     * the ARRANGEMENT was thrown away, and no amount of correct colour brings it
+     * back.
+     *
+     * So a container that actually lays its children out — `display:flex` or
+     * `grid` — and has two or more of them that produced something becomes a
+     * GROUP carrying its direction. Anything else flattens, because a `<div>` that
+     * merely wraps is not a design decision and reproducing it would nest the
+     * result ten deep for nothing.
+     */
     const leaves = (root) => {
-        const out = [];
+        const walkChildren = (el) => {
+            const kids = [];
+            for (const child of Array.from(el.children)) {
+                for (const c of walk(child))
+                    kids.push(c);
+            }
+            return kids;
+        };
         const walk = (el) => {
-            if (out.length >= limits.maxPerSection)
-                return;
+            // ONE BOUND, on the whole import. There used to be a second, per section,
+            // and it kept doing the same wrong job under a new number: a page whose
+            // <body> has a single child is ONE section, so the per-section cap became
+            // the page cap and truncated it — news.ycombinator.com captured 84 links
+            // and 45 lines and lost the rest at exactly 120. Two limits for one
+            // quantity means the tighter one is always the real limit, and nobody
+            // remembers which that is.
+            if (taken.nodes >= limits.maxNodes) {
+                skip('over-node-limit');
+                return [];
+            }
             const tag = el.tagName;
             if (IGNORE.has(tag)) {
                 skip(tag.toLowerCase());
-                return;
+                return [];
             }
             if (!visible(el)) {
                 skip('hidden');
-                return;
+                return [];
             }
             if (HEADINGS.has(tag)) {
                 const text = clean(el.textContent);
-                if (text)
-                    out.push({ kind: 'heading', level: Number(tag.slice(1)), text });
-                return;
+                if (!text)
+                    return [];
+                taken.nodes++;
+                return [{ kind: 'heading', level: Number(tag.slice(1)), text }];
             }
             if (tag === 'IMG') {
                 const src = el.getAttribute('src');
                 if (!src || src.startsWith('data:')) {
                     skip('image-without-src');
-                    return;
+                    return [];
                 }
-                // BOUNDED, because every image is an upload. A sponsors wall is a real
-                // page shape — one measured at 36 logos in four sections — and importing
-                // it means 36 sequential HTTP round trips inside a single tool call,
-                // which is slow, half-fails in interesting ways, and is almost never
-                // what the caller wanted from "import this page".
                 if (taken.images >= limits.maxImages) {
                     skip('over-image-limit');
-                    return;
+                    return [];
                 }
                 taken.images++;
-                out.push({ kind: 'image', src: abs(src), alt: clean(el.getAttribute('alt')) });
-                return;
+                taken.nodes++;
+                return [{ kind: 'image', src: abs(src), alt: clean(el.getAttribute('alt')) }];
             }
-            if (tag === 'A' && looksLikeButton(el)) {
+            if (tag === 'A') {
                 const text = clean(el.textContent);
-                const href = el.getAttribute('href');
+                // A LINK THAT IS NOT A BUTTON IS STILL A LINK. It used to contribute
+                // NOTHING, and on a page whose content IS a list of links that is the
+                // whole page: news.ycombinator.com lost 1,595 characters of story titles
+                // and bylines that way. The platform has no inline-link element — its
+                // own idiom is a `button` carrying `href`, styled flat — so that is what
+                // an unpainted link becomes, and the variant is what keeps it from
+                // arriving as a call to action.
+                if (text && el.children.length === 0) {
+                    const href = el.getAttribute('href');
+                    taken.nodes++;
+                    return [{
+                            kind: 'button',
+                            variant: looksLikeButton(el) ? 'cta' : 'link',
+                            text,
+                            ...(href ? { href: abs(href) } : {}),
+                        }];
+                }
+                if (looksLikeButton(el) && text) {
+                    const href = el.getAttribute('href');
+                    taken.nodes++;
+                    return [{ kind: 'button', variant: 'cta', text, ...(href ? { href: abs(href) } : {}) }];
+                }
+                // A LINK WITH MARKUP INSIDE IT IS STILL A LINK. `<a><span>Docs</span></a>`
+                // has children, so it fell through to the child walk — and when those
+                // children produced nothing renderable (an icon font's ligature, a
+                // decorative span) the link's words went with them. Same shape as the
+                // text fallback below, and for the same reason: offer your own content
+                // only when nothing inside offered any.
+                const inner = walkChildren(el);
+                if (inner.length > 0)
+                    return inner;
                 if (text) {
-                    out.push({ kind: 'button', text, ...(href ? { href: abs(href) } : {}) });
+                    const href = el.getAttribute('href');
+                    taken.nodes++;
+                    return [{ kind: 'button', variant: 'link', text, ...(href ? { href: abs(href) } : {}) }];
                 }
-                return;
+                return [];
             }
             if (tag === 'UL' || tag === 'OL') {
                 const items = Array.from(el.querySelectorAll('li'))
                     .map((li) => clean(li.textContent))
                     .filter(Boolean);
-                if (items.length)
-                    out.push({ kind: 'list', items });
-                return;
+                if (!items.length)
+                    return [];
+                taken.nodes++;
+                return [{ kind: 'list', items }];
             }
             if (tag === 'P' || tag === 'BLOCKQUOTE') {
                 const text = clean(el.textContent);
-                if (text)
-                    out.push({ kind: 'text', text });
-                return;
+                if (!text)
+                    return [];
+                taken.nodes++;
+                return [{ kind: 'text', text }];
             }
-            for (const child of Array.from(el.children))
-                walk(child);
+            const kids = walkChildren(el);
+            if (kids.length > 0) {
+                const cs = getComputedStyle(el);
+                const lays = cs.display === 'flex' || cs.display === 'grid' ||
+                    cs.display === 'inline-flex' || cs.display === 'inline-grid';
+                // A ROW is worth keeping; a column is what the page already is, so
+                // wrapping one in a group would add a level that renders identically.
+                const row = cs.display.indexOf('grid') >= 0
+                    ? true
+                    : cs.flexDirection === 'row' || cs.flexDirection === 'row-reverse';
+                if (lays && row && kids.length >= 2) {
+                    taken.nodes++;
+                    return [{ kind: 'group', direction: 'row', wrap: cs.flexWrap === 'wrap', children: kids }];
+                }
+                return kids;
+            }
+            // THE TEXT FALLBACK, and it is most of the web. Capturing only <p> meant a
+            // page whose prose sits in a <div>, a <td> or a <span> came back EMPTY:
+            // measured, news.ycombinator.com (a table layout) and tailwindcss.com both
+            // kept 0 of ~4,000 and ~6,000 characters.
+            //
+            // Safe because it only fires when nothing INSIDE offered anything, so a
+            // paragraph is never taken twice — once through its <p> and again through
+            // the <div> around it. Bounded because a fallback that fires high in the
+            // tree would otherwise carry a whole page as one string.
+            const own = clean(el.textContent);
+            if (own && own.length <= limits.maxTextChars) {
+                taken.nodes++;
+                return [{ kind: 'text', text: own }];
+            }
+            if (own)
+                skip('text-too-long');
+            return [];
         };
-        walk(root);
-        return out;
+        return walk(root);
     };
     // SECTION CANDIDATES, widest first: a page that marks its bands up
     // semantically is read that way, and one that does not falls back to the
@@ -154,22 +245,59 @@ function capturePage(limits) {
     // document is one candidate too, and keeping THAT would reduce every page to a
     // single band. The finest ones are the page's actual bands.
     candidates = candidates.filter((el) => !candidates.some((o) => o !== el && el.contains(o)));
-    const sections = [];
-    for (const el of candidates) {
-        if (sections.length >= limits.maxSections) {
-            skip('over-section-limit');
-            break;
-        }
-        if (!visible(el)) {
-            skip('hidden');
-            continue;
-        }
-        const children = leaves(el);
-        if (children.length === 0) {
-            skip('empty-section');
-            continue;
+    // THE SOURCE'S OWN HEADER AND FOOTER ARE NEVER WANTED. The target site has its
+    // own, as shared globals, and importing somebody else's navigation onto a
+    // storefront is a second menu pointing at a different website. Only the
+    // PAGE-LEVEL ones are dropped — a `<header>` inside a section is a hero, and
+    // excluding those would lose the first thing on most landing pages.
+    const chrome = new Set();
+    for (const el of Array.from(document.body.children)) {
+        if (el.tagName === 'HEADER' || el.tagName === 'FOOTER')
+            chrome.add(el);
+    }
+    const build = (from) => {
+        const acc = [];
+        for (const el of from) {
+            if (chrome.has(el)) {
+                skip('page-chrome');
+                continue;
+            }
+            if (acc.length >= limits.maxSections) {
+                skip('over-section-limit');
+                break;
+            }
+            if (!visible(el)) {
+                skip('hidden');
+                continue;
+            }
+            const children = leaves(el);
+            if (children.length === 0) {
+                skip('empty-section');
+                continue;
+            }
+            // PINNING IS THE ONE BEHAVIOUR WORTH CARRYING OVER, and the only one this
+            // importer reads off computed style rather than off the tree. A sticky
+            // category bar or a fixed buy bar is a layout DECISION — the section is
+            // there to stay in view — and a copy that scrolls away is not the same
+            // section. Sticky and fixed only: `absolute` and `relative` describe where
+            // a box sits inside a layout this import is not copying, so carrying them
+            // would place a section against coordinates that no longer exist.
+            const pos = getComputedStyle(el).position;
+            const pinned = pos === 'sticky' || pos === 'fixed' ? pos : undefined;
+            acc.push({ kind: 'section', children, ...(pinned ? { pinned } : {}) });
         }
-        sections.push({ kind: 'section', children });
+        return acc;
+    };
+    let sections = build(candidates);
+    // THE FALLBACK HAS TO FIRE ON AN EMPTY RESULT, not only on an empty candidate
+    // LIST. A page can offer `<section>` elements that hold nothing this platform
+    // renders — a wrapper around a canvas, a slot filled by script later — and the
+    // old order took "we found candidates" as "we found content", so the whole
+    // page came back empty. Measured: tailwindcss.com kept 0 of 6,004 characters
+    // while reporting one skipped empty section.
+    if (sections.length === 0) {
+        const main = document.querySelectorAll('main')[0] ?? document.body;
+        sections = build(Array.from(main.children));
     }
     return { url: here, title: clean(document.title), sections, skipped };
 }
@@ -183,8 +311,9 @@ function capturePage(limits) {
 export async function capture(url, opts = {}) {
     const limits = {
         maxSections: opts.maxSections ?? 24,
-        maxPerSection: opts.maxPerSection ?? 40,
         maxImages: opts.maxImages ?? 24,
+        maxTextChars: opts.maxTextChars ?? 1200,
+        maxNodes: opts.maxNodes ?? 400,
     };
     let browser;
     try {

package/dist/vision/shoot.js

@@ -90,15 +90,26 @@ export async function closeBrowser() {
         await b.close().catch(() => { });
 }
 /**
- * A kept browser is a child process, and a child process outlives a parent
- * that forgets it. `beforeExit` fires when the event loop drains and CAN await
- * the close (`exit` cannot). A signal kills the loop without draining it, so
- * SIGINT/SIGTERM close Chrome too and then re-raise so the exit code is the
- * one the signal would have produced. Registered once, at module load.
+ * A kept browser is a child process, and a child process outlives a parent that
+ * forgets it. SIGINT/SIGTERM close Chrome and then re-raise, so the exit code is
+ * the one the signal would have produced. That is the path the MCP server
+ * actually takes, because a stdio server is stopped by its client.
+ *
+ * THERE USED TO BE A `beforeExit` HANDLER HERE TOO, and it could never fire.
+ * `beforeExit` runs when the event loop DRAINS, and an open browser connection
+ * is exactly what keeps it from draining — so in the one situation the handler
+ * described (a caller that finished and forgot to close) it was unreachable, and
+ * in the other (nothing open) it had nothing to do. Proved by measurement: a
+ * script that took one screenshot and returned was still alive twenty seconds
+ * later, and two of them were killed by the OS for memory during this repo's own
+ * development. `playwright-core` exposes no `browser.process()` for `launch()`,
+ * so there is nothing to `unref` and no way to make it reachable.
+ *
+ * SO THE CONTRACT IS EXPLICIT: a caller that is not a long-running server must
+ * call `closeBrowser()` when it is done — a `finally` block, not a hope. The
+ * pooling is deliberate (a vision loop shoots constantly and must not pay a
+ * launch each time); the cost of it is this one line at every other call site.
  */
-process.once('beforeExit', () => {
-    void closeBrowser();
-});
 for (const signal of ['SIGINT', 'SIGTERM']) {
     process.once(signal, () => {
         void closeBrowser().finally(() => process.kill(process.pid, signal));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sbuilder-mcp",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "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",