sbuilder-mcp 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -6,6 +6,22 @@ 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

package/CHANGELOG.vi.md

@@ -6,6 +6,22 @@ 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

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. */
@@ -204,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.
@@ -219,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 ?? {});
@@ -219,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: {
@@ -227,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/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

@@ -89,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) {

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

@@ -84,6 +84,14 @@ function capturePage(limits) {
      * result ten deep for nothing.
      */
     const leaves = (root) => {
+        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) => {
             // 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
@@ -150,6 +158,21 @@ function capturePage(limits) {
                     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) {
+                    const href = el.getAttribute('href');
+                    taken.nodes++;
+                    return [{ kind: 'button', variant: 'link', text, ...(href ? { href: abs(href) } : {}) }];
+                }
+                return [];
             }
             if (tag === 'UL' || tag === 'OL') {
                 const items = Array.from(el.querySelectorAll('li'))
@@ -167,11 +190,7 @@ function capturePage(limits) {
                 taken.nodes++;
                 return [{ kind: 'text', text }];
             }
-            const kids = [];
-            for (const child of Array.from(el.children)) {
-                for (const c of walk(child))
-                    kids.push(c);
-            }
+            const kids = walkChildren(el);
             if (kids.length > 0) {
                 const cs = getComputedStyle(el);
                 const lays = cs.display === 'flex' || cs.display === 'grid' ||
@@ -256,7 +275,16 @@ function capturePage(limits) {
                 skip('empty-section');
                 continue;
             }
-            acc.push({ kind: 'section', children });
+            // 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 } : {}) });
         }
         return acc;
     };

package/package.json

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