sbuilder-mcp 0.36.1 → 0.38.0

package/CHANGELOG.md

@@ -6,6 +6,25 @@ 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.38.0] - 2026-09-11
+
+### Added
+- The catalog gained a 112th element, spline-scene: an interactive 3D scene embedded from a Spline viewer link, seeded by default with a real scene from Spline's own demo project, with a warning at creation time telling the caller to replace it with the merchant's own export before publishing.
+- config.animation grew from five keys to ten (intensity, trigger, range, repeat, and alternate join active, type, easing, delay, and duration), including a new `trigger: "view"` for reveal-on-scroll animation, compiled as a pure-CSS animation-timeline override with no added script.
+- sb_traits_for now returns an animation_values field listing every legal value for each config.animation key (all 46 types, 7 easings, every intensity and trigger) for any element that carries an animation control.
+- sb_set now warns when config.animation combines alternate:true with a finite repeat count, since that combination publishes a node that finishes on its opacity:0 keyframe and is invisible to every visitor, and when intensity or trigger is set to a value the platform does not recognize.
+
+### Changed
+- config.animation is no longer base-only: sb_set now writes it per breakpoint like any other config key, instead of always routing it to base, so an animation can now be turned off on mobile.
+
+## [0.37.0] - 2026-09-11
+
+### Added
+- sb_import and sb_import_site now take a `nav_timeout_ms` argument (5,000-120,000ms, default 30,000) to raise how long a capture waits for a slow origin to answer at all.
+
+### Fixed
+- sb_import_site's timeout failure now reports the number of seconds the page actually waited and suggests raising `nav_timeout_ms`, instead of always naming the unmodified default even after a caller had already raised it.
+
 ## [0.36.1] - 2026-09-11
 
 - fix(import,api): a capture waited on iframes, and a recovery list was unreadable

package/CHANGELOG.vi.md

@@ -6,6 +6,25 @@ 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.38.0] - 2026-09-11
+
+### Added
+- Catalog có thêm element thứ 112, spline-scene: một cảnh 3D tương tác được nhúng từ link viewer của Spline, mặc định được gán sẵn một cảnh thật từ project demo của chính Spline, kèm cảnh báo ngay lúc tạo yêu cầu caller thay bằng file export của merchant trước khi publish.
+- config.animation tăng từ năm key lên mười key (intensity, trigger, range, repeat và alternate được thêm bên cạnh active, type, easing, delay và duration), trong đó có `trigger: "view"` mới cho hiệu ứng xuất hiện khi cuộn trang, được biên dịch thành một override CSS thuần bằng animation-timeline, không cần thêm script.
+- sb_traits_for giờ trả về thêm trường animation_values liệt kê mọi giá trị hợp lệ cho từng key của config.animation (đủ 46 type, 7 easing, mọi intensity và trigger) với bất kỳ element nào có control animation.
+- sb_set giờ cảnh báo khi config.animation kết hợp alternate:true với một số lần repeat hữu hạn, vì tổ hợp này publish một node kết thúc ở keyframe opacity:0 và không visitor nào nhìn thấy được, cũng như khi intensity hoặc trigger được đặt một giá trị mà nền tảng không nhận ra.
+
+### Changed
+- config.animation không còn base-only nữa: sb_set giờ ghi giá trị này theo từng breakpoint như mọi config key khác, thay vì luôn dồn về base, nên giờ có thể tắt animation riêng trên mobile.
+
+## [0.37.0] - 2026-09-11
+
+### Added
+- sb_import và sb_import_site giờ nhận thêm tham số `nav_timeout_ms` (5.000-120.000ms, mặc định 30.000) để tăng thời gian chờ trang trả lời khi nguồn phản hồi chậm.
+
+### Fixed
+- Lỗi timeout của sb_import_site giờ báo đúng số giây trang thực sự đã chờ và gợi ý tăng `nav_timeout_ms`, thay vì luôn nêu giá trị mặc định chưa đổi ngay cả khi caller đã tự tăng nó.
+
 ## [0.36.0] - 2026-09-11
 
 ### Added

package/dist/catalog/element-search.js

@@ -1,5 +1,5 @@
 import { ELEMENTS, TRAIT_WRITES } from './elements.generated.js';
-import { animationVocabulary, vocabulariesForWrites } from '../domains/site/vocabulary.js';
+import { animationValues, animationVocabulary, vocabulariesForWrites } from '../domains/site/vocabulary.js';
 import { neverTranslatedOn, translatableSpecials } from '../domains/site/translate.js';
 /** Eight to choose from; the hints for the chosen one come with sb_traits_for. */
 export const DEFAULT_CATALOG_LIMIT = 8;
@@ -130,7 +130,9 @@ export function traitsFor(type, control) {
         // with a required gate, and the three ways to get it wrong all render
         // NOTHING rather than something else. An element that does not offer the
         // control says nothing, so this is silent on the other 38.
-        ...(el.controls.includes('animation') ? { animation: animationVocabulary() } : {}),
+        ...(el.controls.includes('animation')
+            ? { animation: animationVocabulary(), animation_values: animationValues() }
+            : {}),
         isContainer: el.isContainer,
         isRootOnly: el.isRootOnly,
         childAllows: el.childAllows,

package/dist/catalog/elements.generated.js

@@ -1,5 +1,5 @@
 export const ELEMENT_SOURCE = {
-    "count": 111,
+    "count": 112,
     "docSchemaVersion": 2
 };
 export const ELEMENTS = {
@@ -3686,6 +3686,146 @@ export const ELEMENTS = {
             "player"
         ]
     },
+    "spline-scene": {
+        "type": "spline-scene",
+        "label": "Spline scene",
+        "category": "media",
+        "isContainer": false,
+        "isRootOnly": false,
+        "locked": false,
+        "hideInLayer": false,
+        "childAllows": [],
+        "defaults": {
+            "specials": {
+                "sceneUrl": "https://prod.spline.design/HqdfCmOueigtautT/scene.splinecode",
+                "posterUrl": "",
+                "sceneControls": []
+            },
+            "style": {
+                "width": "100%",
+                "height": "480px"
+            },
+            "config": {
+                "background": "transparent",
+                "eventsTarget": "local",
+                "mobileMode": "scene"
+            }
+        },
+        "inspector": [
+            {
+                "tab": "general",
+                "groups": [
+                    {
+                        "key": "size",
+                        "label": "Size",
+                        "controls": [
+                            "width_select",
+                            "size_bounds"
+                        ]
+                    },
+                    {
+                        "key": "spline",
+                        "label": "Spline",
+                        "controls": [
+                            "spline_source"
+                        ]
+                    },
+                    {
+                        "key": "scene_display",
+                        "label": "Display",
+                        "controls": [
+                            "scene_display"
+                        ]
+                    },
+                    {
+                        "key": "scene_controls",
+                        "label": "Scene controls",
+                        "controls": [
+                            "scene_controls"
+                        ]
+                    },
+                    {
+                        "key": "shape",
+                        "label": "Shape",
+                        "controls": [
+                            "border",
+                            "corner",
+                            "shadow"
+                        ]
+                    }
+                ]
+            },
+            {
+                "tab": "advanced",
+                "groups": [
+                    {
+                        "key": "spacing",
+                        "label": "Spacing",
+                        "controls": [
+                            "padding_margin"
+                        ]
+                    },
+                    {
+                        "key": "display",
+                        "label": "Display",
+                        "controls": [
+                            "display"
+                        ]
+                    },
+                    {
+                        "key": "animation",
+                        "label": "Animation",
+                        "controls": [
+                            "animation"
+                        ]
+                    },
+                    {
+                        "key": "class_css",
+                        "label": "Class",
+                        "controls": [
+                            "class_css"
+                        ]
+                    }
+                ]
+            }
+        ],
+        "controls": [
+            "width_select",
+            "size_bounds",
+            "spline_source",
+            "scene_display",
+            "scene_controls",
+            "border",
+            "corner",
+            "shadow",
+            "padding_margin",
+            "display",
+            "animation",
+            "class_css"
+        ],
+        "description": "An interactive 3D scene made in Spline, embedded from its viewer URL.",
+        "useWhen": [
+            "For a hero or product moment that should move in 3D as the visitor scrolls or hovers",
+            "When the merchant already designs in Spline and has a .splinecode link"
+        ],
+        "avoidWhen": [
+            "For a plain product photo — use image",
+            "For a video — use video / youtube / vimeo",
+            "More than three 3D scenes on one page (each one costs ~600 KB of JS once it scrolls into view)"
+        ],
+        "contentTips": [
+            "Paste the link from Spline: Export → Viewer → copy link (…/scene.splinecode)",
+            "Add a poster image so the box is not blank while the scene loads"
+        ],
+        "semantics": [
+            "3d",
+            "spline",
+            "scene",
+            "webgl",
+            "animation",
+            "interactive"
+        ]
+    },
     "vimeo": {
         "type": "vimeo",
         "label": "Vimeo",
@@ -36195,7 +36335,6 @@ export const BASE_ONLY_CONFIG = [
     "collectionId",
     "collectionType",
     "quantity",
-    "animation",
     "rowLimit"
 ];
 /**
@@ -36207,20 +36346,38 @@ export const BASE_ONLY_EXCEPTIONS = [
     "quantity-button:iconSize"
 ];
 /**
- * The ENTRANCE ANIMATION's vocabulary — config.animation, offered by 73 of the
- * 111 element types and describable by nothing until now.
+ * The ENTRANCE ANIMATION's vocabulary — config.animation, offered by most of
+ * the element library and describable by nothing until this table existed.
  *
  * Three ways to miss, all silent (AnimationTypeOf answers "" and no keyframes,
  * no rule and no error are emitted, through save, publish and render):
- *   - it is an OBJECT, not a string: {active, type, easing, delay, duration}
+ *   - it is an OBJECT, not a string
  *   - active:true is REQUIRED; a stored type is deliberately NOT consent,
  *     because the panel keeps the type when the switch goes off
  *   - type is a keyframe key spelled with UNDERSCORES: fade_in, never fade-in
  *
  * easing is the mild one: an unrecognised value falls back to "ease".
  *
- * It is also BASE-ONLY (see BASE_ONLY_CONFIG) — render/css.go emits it into the
- * base lane because the config object is read with no responsive merge.
+ * TWO THINGS THIS TABLE USED TO SAY THAT ARE NO LONGER TRUE, kept as a
+ * correction because both were recorded here as settled facts:
+ *
+ *   - IT IS NOT BASE-ONLY ANY MORE. The compiler reads config through
+ *     MergeNamespace and emits per lane, so the key left the platform's
+ *     base-only ledger — and the side effect is the thing merchants ask for
+ *     most, an animation that is off on mobile. A caller still writing it to
+ *     base gets the cascade's fallback layer, which is correct but cannot vary.
+ *   - REVEAL-ON-SCROLL HAS AN ANSWER. trigger:"view" compiles to
+ *     animation-timeline: view() inside an @supports override, so it costs no
+ *     JavaScript and the engines without it keep animating at first paint.
+ *
+ * The object now carries ten keys. intensity travels as CSS variables (a
+ * distance is a quantity, so it reaches the page per breakpoint) and ABSENCE IS
+ * NOT medium — a document with no intensity keeps the old 0.5s fallback.
+ *
+ * alternateNeedsInfinite is the guard worth reading before using repeat:
+ * alternate with an EVEN finite count finishes on the from keyframe, and every
+ * entrance keyframe starts at opacity:0 — so the node publishes INVISIBLE. The
+ * compiler honours alternate only alongside an infinite repeat.
  */
 /**
  * The eight node-style keys a THEME TEXT STYLE controls, and the var prop each
@@ -36237,18 +36394,79 @@ export const BASE_ONLY_EXCEPTIONS = [
 export const TEXT_STYLE_KEYS = [["fontFamily", "family"], ["fontSize", "size"], ["fontWeight", "weight"], ["fontStyle", "style"], ["lineHeight", "line-height"], ["letterSpacing", "letter-spacing"], ["textTransform", "transform"], ["color", "color"]];
 export const ANIMATION = {
     "types": [
+        "blur_in",
+        "bounce",
+        "bounce_in",
+        "elastic_in",
         "fade_in",
+        "fade_in_bottom_left",
+        "fade_in_bottom_right",
+        "fade_in_down",
+        "fade_in_left",
+        "fade_in_right",
+        "fade_in_top_left",
+        "fade_in_top_right",
+        "fade_in_up",
+        "flash",
+        "flip",
+        "flip_in_x",
+        "flip_in_y",
+        "head_shake",
+        "heart_beat",
+        "jack_in_the_box",
+        "jello",
+        "light_speed_in_left",
+        "light_speed_in_right",
+        "pulse",
+        "roll_in",
+        "rotate_in",
+        "rotate_in_down_left",
+        "rotate_in_down_right",
+        "rotate_in_up_left",
+        "rotate_in_up_right",
+        "rubber_band",
+        "shake_x",
+        "shake_y",
         "slide_down",
+        "slide_in_down",
+        "slide_in_left",
+        "slide_in_right",
+        "slide_in_up",
+        "slide_left",
+        "slide_right",
         "slide_up",
-        "zoom_in"
+        "swing",
+        "tada",
+        "wobble",
+        "zoom_in",
+        "zoom_out"
     ],
     "easings": [
         "ease",
         "ease-in",
         "ease-out",
-        "linear"
+        "ease-in-out",
+        "linear",
+        "spring",
+        "bounce"
     ],
     "easingFallback": "ease",
     "durationDefault": 0.5,
+    "intensities": [
+        "soft",
+        "medium",
+        "strong"
+    ],
+    "intensityDurations": {
+        "soft": 0.4,
+        "medium": 0.6,
+        "strong": 0.9
+    },
+    "triggers": [
+        "view"
+    ],
+    "rangeDefault": 60,
+    "repeatMax": 100,
+    "alternateNeedsInfinite": true,
     "readBy": "AnimationTypeOf + CompileEntranceAnimationCSS"
 };

package/dist/catalog/translations.generated.js

@@ -3,7 +3,7 @@
 export const TRANSLATION_SOURCE = {
     "elements": 58,
     "pairs": 141,
-    "neverKeys": 156,
+    "neverKeys": 159,
     "entityTypes": 12
 };
 /** Every entity type a translation record can name, including "node". */
@@ -402,6 +402,7 @@ export const NEVER_TRANSLATED = [
     "payload",
     "picker",
     "poster",
+    "posterUrl",
     "prefillValue",
     "presetCode",
     "provinceField",
@@ -409,6 +410,8 @@ export const NEVER_TRANSLATED = [
     "required",
     "reviewForm",
     "sameDefault",
+    "sceneControls",
+    "sceneUrl",
     "searchBehavior",
     "searchClearSwap",
     "searchDebounceMs",

package/dist/domains/site/inert.js

@@ -26,6 +26,19 @@ export const INERT_ON_ADD = {
             'store that is not in English, set it (e.g. "Trang chủ") or the trail reads half-translated ' +
             'on every product page.',
     },
+    // THE SHARPEST OF THE THREE, because the placeholder is not a placeholder: it
+    // is a REAL scene on Spline's own servers, and it loads, renders and responds
+    // to the mouse. The other two entries here describe an element that looks
+    // finished; this one looks finished AND is somebody else's work, published on
+    // the merchant's domain. `sb_review` reads a correct tree, `sb_look`
+    // photographs a convincing 3D hero, and nothing anywhere says whose it is.
+    'spline-scene': {
+        note: "A spline-scene is born pointing at SPLINE'S OWN DEMO SCENE (specials.sceneUrl defaults to " +
+            'a real prod.spline.design link), so an unset one publishes a 3D hero that loads, moves, ' +
+            "and belongs to somebody else — it looks finished, so no check can flag it. Set sceneUrl " +
+            'to the merchant\'s own export (Spline: Export → Viewer → the …/scene.splinecode link), and ' +
+            'set specials.posterUrl too or the box is blank until the engine chunk arrives.',
+    },
 };
 /** The hint for a type, or null. */
 export function inertHint(type) {

package/dist/domains/site/vocabulary.js

@@ -79,9 +79,31 @@ export function unknownValueNote(key, value) {
  * falls back to `ease`, so the animation still runs — it is a wrong answer, not
  * a missing one.
  *
- * And it is BASE-ONLY, which is a fourth way to lose it — but that one is
- * ROUTED rather than warned about, by `baseonly.ts`, because the platform's
- * ledger names the key and `sb_set` can simply write it to the right layer.
+ * IT WAS BASE-ONLY AND IS NOT ANY MORE, and the correction is kept in that
+ * shape because this file stated it as a settled fact. The compiler used to
+ * index `node.Config["animation"]` with no responsive merge, so a per-breakpoint
+ * write landed where nothing looked and `baseonly.ts` ROUTED it. Adding an
+ * intensity ended that: a distance is a QUANTITY, and this repo's own mandate is
+ * that a quantity reaches the page per breakpoint. `CompileEntranceAnimationCSS`
+ * now takes a `bp` and emits per lane, the key left the platform's ledger, and
+ * the routing stopped on its own — the table is generated, which is exactly why
+ * it could. What the caller gains is the thing merchants ask for most: an
+ * animation that is off on mobile.
+ *
+ * THE OBJECT ALSO GREW TO TEN KEYS, and two of them change what is possible
+ * rather than merely how it looks:
+ *
+ *   - `trigger: "view"` IS REVEAL-ON-SCROLL, which this repo recorded as having
+ *     no answer at all ("the platform has nowhere to put it"). It does now:
+ *     `animation-timeline: view()` inside an `@supports` override, no island and
+ *     no JavaScript, with the engines that lack it still animating at first
+ *     paint. A note that says "you cannot" outlives the thing that made it true,
+ *     and this is the third time that has cost something here.
+ *   - `repeat` + `alternate` is the one combination that publishes an INVISIBLE
+ *     node. `alternate` with an EVEN finite count finishes on the `from`
+ *     keyframe and every entrance keyframe starts at `opacity: 0`, so the author
+ *     sees it on the canvas and a visitor never sees it at all. The compiler
+ *     honours `alternate` only alongside `"infinite"`.
  */
 export const ANIMATION_VOCAB = ANIMATION;
 /**
@@ -96,10 +118,68 @@ export const ANIMATION_VOCAB = ANIMATION;
  * mistake is actually made.
  */
 export function animationVocabulary() {
-    return (`config.animation is an OBJECT: { active: true, type: ${ANIMATION.types.join('|')}, ` +
-        `easing?: ${ANIMATION.easings.join('|')}, delay?, duration? }. active:true is REQUIRED ` +
-        '(a type alone is not consent), the type is UNDERSCORED, and it is base-only. Anything ' +
-        'else renders no animation at all, with no error.');
+    return ('config.animation is an OBJECT, never a string: { active: true, type, easing?, intensity?, ' +
+        'trigger?, delay?, duration?, repeat?, alternate?, range? }. active:true is REQUIRED (a type ' +
+        'alone is not consent) and the type is UNDERSCORED (fade_in, never fade-in); either miss ' +
+        'renders no animation at all, with no error. Written per breakpoint like any config, so it ' +
+        'can be off on mobile. See animation_values below for what each key accepts.');
+}
+/**
+ * THE SAME FACTS AS DATA, because forty-six type names are not a sentence.
+ *
+ * The line above used to enumerate every type, which worked while there were
+ * four and became 848 bytes of prose the moment the platform shipped 46 — and
+ * the budget test caught it, correctly, for the second time on this same field.
+ * The first catch (a six-field object, 12,396 bytes) moved the long form OUT of
+ * the trait sheet; this one moves the ENUMERATION out of the prose. What is left
+ * in the sentence is what decides whether a write does anything at all.
+ *
+ * It rides on `sb_traits_for`, which answers for ONE element per call, and not
+ * on `sb_catalog_search`, which answers for many — so the cost is paid once by
+ * the caller who has already chosen the element it is about to animate.
+ *
+ * Every value here is GENERATED from the Go that renders, so a platform that
+ * adds a trigger or an intensity brings it to this sheet on the next codegen,
+ * and one that drops a field stops claiming it.
+ */
+export function animationValues() {
+    const a = ANIMATION;
+    const mid = a.intensities[Math.floor(a.intensities.length / 2)];
+    return {
+        type: a.types,
+        easing: { values: a.easings, unknown_falls_back_to: a.easingFallback },
+        // `absence is not the middle setting` is the platform's own point and the
+        // one reading a caller gets wrong without being told; the rest of the
+        // intensity story is a duration table, which speaks for itself.
+        ...(a.intensities.length
+            ? {
+                intensity: {
+                    values: a.intensities,
+                    implies_duration_s: a.intensityDurations,
+                    note: `omitting it is NOT "${mid}" — it keeps the ${a.durationDefault}s default instead`,
+                },
+            }
+            : {}),
+        // THE ONE ENTRY THAT MUST BE PROACTIVE. Every other trap here is caught by
+        // animationNote at the moment of the mistake — but there is no mistake to
+        // catch in never knowing a capability exists, so reveal-on-scroll has to be
+        // discoverable from the sheet itself.
+        ...(a.triggers.length
+            ? {
+                trigger: {
+                    values: a.triggers,
+                    default: 'omitted = runs at first paint',
+                    view: `reveal-on-scroll (animation-timeline), range = % of entry, default ${a.rangeDefault}`,
+                },
+            }
+            : {}),
+        ...(a.repeatMax ? { repeat: `1-${a.repeatMax} or "infinite"; above that is clamped` } : {}),
+        ...(a.alternateNeedsInfinite
+            ? { alternate: 'requires repeat:"infinite" — DROPPED on a finite count, which would end invisible' }
+            : {}),
+        duration_default_s: a.durationDefault,
+        read_by: a.readBy,
+    };
 }
 /**
  * The warning for a `config.animation` write that will not animate.
@@ -138,6 +218,33 @@ export function animationNote(value) {
         notes.push(`easing ${JSON.stringify(e)} is outside ${ANIMATION.easings.join(', ')}, so the renderer ` +
             `uses "${ANIMATION.easingFallback}" — the animation runs, with a curve you did not choose`);
     }
+    const i = value.intensity;
+    if (i !== undefined && (typeof i !== 'string' || !ANIMATION.intensities.includes(i))) {
+        // Same family as easing — it runs — but the miss is quieter still: no
+        // variables are emitted and the keyframes fall back to their own literals,
+        // so the node animates at a distance nobody chose and nothing looks broken.
+        notes.push(`intensity ${JSON.stringify(i)} is outside ${ANIMATION.intensities.join(', ')}, so no ` +
+            'intensity variables are emitted and the keyframes use their built-in distances');
+    }
+    const tr = value.trigger;
+    if (tr !== undefined && (typeof tr !== 'string' || !ANIMATION.triggers.includes(tr))) {
+        notes.push(`trigger ${JSON.stringify(tr)} is not ${ANIMATION.triggers.map((v) => JSON.stringify(v)).join(' or ')}, ` +
+            'so the animation runs at first paint rather than on scroll — stored, published, and ignored');
+    }
+    // THE ONE THAT PUBLISHES AN INVISIBLE NODE. `alternate` is honoured only
+    // alongside an infinite repeat: with an even finite count the animation
+    // finishes on the `from` keyframe, and every entrance keyframe starts at
+    // opacity:0. The author sees it play on the canvas and the visitor sees
+    // nothing at all, with no error anywhere to explain it.
+    if (ANIMATION.alternateNeedsInfinite && value.alternate === true && value.repeat !== 'infinite') {
+        notes.push('alternate:true is DROPPED unless repeat is "infinite" — with an even finite count the ' +
+            'animation would finish on the from keyframe, which is opacity:0, and publish a node no ' +
+            'visitor can see; the renderer refuses that rather than shipping it');
+    }
+    if (typeof value.repeat === 'number' && ANIMATION.repeatMax && value.repeat > ANIMATION.repeatMax) {
+        notes.push(`repeat ${value.repeat} is clamped to ${ANIMATION.repeatMax} — the count reaches CSS as a ` +
+            'number, and a document is not a trusted source');
+    }
     if (!notes.length)
         return null;
     return `config.animation will not do what this says. ${notes.join('. ')}.`;

package/dist/tools/importpage.js

@@ -193,6 +193,13 @@ export function registerImportTools(server, ctx, session) {
                 .max(100)
                 .optional()
                 .describe('Default 24 — every image is an upload'),
+            nav_timeout_ms: z
+                .number()
+                .int()
+                .min(5_000)
+                .max(120_000)
+                .optional()
+                .describe('How long to wait for a page to answer at all. Default 30000; raise it for a slow origin'),
             max_nodes: z
                 .number()
                 .int()
@@ -207,7 +214,7 @@ 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, max_nodes, upload_images, dry_run }) => {
+    }, async ({ url, site_id: given, max_sections, max_images, max_nodes, nav_timeout_ms, 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
@@ -217,6 +224,7 @@ export function registerImportTools(server, ctx, session) {
             maxSections: max_sections,
             maxImages: max_images,
             maxNodes: max_nodes,
+            navTimeoutMs: nav_timeout_ms,
         });
         const tokens = tokensFromPage(doc.doc);
         const images = imageSources(shot.sections);
@@ -332,13 +340,20 @@ export function registerImportTools(server, ctx, session) {
             exclude: z.array(z.string()).optional(),
             max_images: z.number().int().min(0).max(200).optional().describe('Default 24, whole import'),
             max_nodes: z.number().int().min(1).max(1000).optional().describe('Per page, default 300'),
+            nav_timeout_ms: z
+                .number()
+                .int()
+                .min(5_000)
+                .max(120_000)
+                .optional()
+                .describe('How long to wait for a page to answer at all. Default 30000; raise it for a slow origin'),
             upload_images: z.boolean().optional(),
             homepage: z.boolean().optional().describe("Entry into this site's home page, default true"),
             nav: z.boolean().optional().describe('Shared header linking the new pages, default true'),
             dry_run: z.boolean().optional(),
         },
         annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
-    }, async ({ url, site_id: given, max_pages, depth, include, exclude, max_images, max_nodes, upload_images, homepage, nav, dry_run, }) => {
+    }, async ({ url, site_id: given, max_pages, depth, include, exclude, max_images, max_nodes, nav_timeout_ms, upload_images, homepage, nav, dry_run, }) => {
         const siteId = siteFor(ctx, given);
         const entry = normalizeUrl(url);
         if (!entry) {
@@ -470,7 +485,7 @@ export function registerImportTools(server, ctx, session) {
         // 9,829px of catalogue across a dozen collection bands, and 300 cut it
         // off in the middle of the third. A cap is here to stop a runaway page,
         // not to decide how much of an ordinary one survives.
-        { maxImages: max_images ?? 60, maxNodes: max_nodes ?? 900 });
+        { maxImages: max_images ?? 60, maxNodes: max_nodes ?? 900, navTimeoutMs: nav_timeout_ms });
         const byUrl = new Map(shots.map((s) => [s.url, s]));
         // ONE UPLOAD PER IMAGE FOR THE WHOLE SITE, not per page. A logo, a payment
         // strip and a footer badge appear on every page of a real site, and

package/dist/vision/capture.js

@@ -1075,6 +1075,19 @@ function capturePage(limits) {
         }
         restore(bestState);
     }
+    // WHAT FRACTION OF THE PAGE A READER SEES SURVIVED, reported rather than
+    // assumed. Both halves are already computed above for the fallback decision,
+    // so this costs nothing and closes the one failure a capture cannot express:
+    // SETTLING IS NOT FAILING. MEASURED on ttgshop.vn while the origin was taking
+    // 45s to answer — 6 text nodes and 114 characters of a page holding 2,396,
+    // 4.8%, `skipped` empty, no error anywhere. A thin import that says so is one
+    // a caller retries; a silent one ships.
+    //
+    // Against the honest denominator this file already argues for: page chrome is
+    // skipped ON PURPOSE, so counting it would make every correct import of a
+    // nav-heavy site look broken.
+    const kept = textOf(sections);
+    const coverage = contentChars > 0 ? Math.round((kept / contentChars) * 100) : 100;
     const link = Array.from(document.querySelectorAll('link[rel="canonical"]'))[0];
     const canonical = link ? (link.getAttribute('href') ?? '') : '';
     return {
@@ -1084,6 +1097,7 @@ function capturePage(limits) {
         ...(forms.length ? { forms } : {}),
         sections,
         skipped,
+        coverage,
     };
 }
 /**
@@ -1123,7 +1137,23 @@ async function withBrowser(fn) {
  * `shoot.ts` gives: a page with a poller never goes idle, and waiting for that
  * spends the whole budget on a timeout that cannot resolve.
  */
-async function readPage(browser, url, width, work) {
+/**
+ * How long to wait for a page to answer AT ALL, and why it is a knob.
+ *
+ * Thirty seconds is right for the web and wrong for one site on one afternoon.
+ * MEASURED on ttgshop.vn, the same shop this importer was built against: it
+ * answered in 4.6s all morning and then took 45 SECONDS for 151 KB, with the
+ * next request not answering inside 45s at all. Nothing about the page changed
+ * — the origin was simply having a bad day, which is the ordinary condition of
+ * the sites a merchant actually asks to import.
+ *
+ * The default stays 30s, because a caller who says nothing wants a bound rather
+ * than a hang. What was wrong was that the number could not be raised at all:
+ * an import of your OWN slow site had no recourse, and the failure arrives as a
+ * bare Playwright timeout that names the browser rather than the remedy.
+ */
+const NAV_TIMEOUT_MS = 30_000;
+async function readPage(browser, url, width, work, navMs = NAV_TIMEOUT_MS, settleMs) {
     let page;
     try {
         page = await browser.newPage({ viewport: { width, height: 900 } });
@@ -1142,14 +1172,14 @@ async function readPage(browser, url, width, work) {
         // earlier: the right question is "has the DOM stopped changing", and
         // `settleDom` answers it directly and bounded. A page that genuinely needs
         // its images is the SHOOT path's problem, and that one still waits.
-        await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
+        await page.goto(url, { waitUntil: 'domcontentloaded', timeout: navMs });
         // THE SAME SETTLE `sb_look` USES, not a flat sleep. A fixed 600ms is wrong
         // at both ends: example.com is finished long before it, and a page that
         // builds itself with scripts is not finished after it — which is exactly the
         // page an import is most likely to be pointed at. `settleDom` asks the
         // question actually being asked (has the page stopped changing) and answers
         // when it becomes true, bounded so a page that never settles is still read.
-        await settleDom(page);
+        await settleDom(page, settleMs);
         return await work(page);
     }
     finally {
@@ -1164,10 +1194,32 @@ function limitsFrom(opts) {
         maxNodes: opts.maxNodes ?? 400,
     };
 }
+/**
+ * A read that failed, said in the caller's terms.
+ *
+ * Playwright's own timeout names the browser and the wait — "page.goto: Timeout
+ * 30000ms exceeded" — which is true and tells a merchant nothing they can act
+ * on. The remedy is a number they can raise, so the message carries it.
+ */
+function readFailure(e) {
+    const msg = e.message ?? String(e);
+    // THE NUMBER COMES OUT OF THE ERROR, never out of the default. The first
+    // version of this printed NAV_TIMEOUT_MS, so a caller who had already raised
+    // the budget to 90s was told the page "did not answer within 30s" — a
+    // confidently wrong number, and one that sends them to change a setting they
+    // had just changed.
+    const hit = /Timeout (\d+)ms exceeded/.exec(msg);
+    if (hit) {
+        const secs = Math.round(Number(hit[1]) / 1000);
+        return (`the page did not answer within ${secs}s. A slow origin is ordinary — raise ` +
+            'nav_timeout_ms and try again, or import fewer pages at once.');
+    }
+    return msg.slice(0, 160);
+}
 /** Open a URL and capture it. */
 export async function capture(url, opts = {}) {
     const limits = limitsFrom(opts);
-    return withBrowser((browser) => readPage(browser, url, opts.width ?? 1440, (page) => page.evaluate(capturePage, limits)));
+    return withBrowser((browser) => readPage(browser, url, opts.width ?? 1440, (page) => page.evaluate(capturePage, limits), opts.navTimeoutMs, opts.settleMs));
 }
 /**
  * Capture several pages through one browser.
@@ -1184,11 +1236,11 @@ export async function captureMany(urls, opts = {}) {
         const out = [];
         for (const url of urls) {
             try {
-                const result = (await readPage(browser, url, opts.width ?? 1440, (page) => page.evaluate(capturePage, limits)));
+                const result = (await readPage(browser, url, opts.width ?? 1440, (page) => page.evaluate(capturePage, limits), opts.navTimeoutMs, opts.settleMs));
                 out.push({ url, ok: true, result });
             }
             catch (e) {
-                out.push({ url, ok: false, why: e.message.slice(0, 160) });
+                out.push({ url, ok: false, why: readFailure(e) });
             }
         }
         return out;

package/dist/vision/shoot.js

@@ -172,7 +172,7 @@ export async function shoot(url, opts = {}) {
  * polling widget from holding the shot forever. A page that never settles is
  * photographed anyway — a late picture beats none.
  */
-export async function settleDom(page) {
+export async function settleDom(page, capMs = 2_000) {
     await page
         .evaluate(({ quiet, cap }) => new Promise((resolve) => {
         const start = Date.now();
@@ -194,7 +194,14 @@ export async function settleDom(page) {
                 resolve();
             }
         }, 50);
-    }), { quiet: 250, cap: 2_000 })
+    }), 
+    // The CAP is a knob because 2,000 ms is right for a healthy origin and
+    // wrong for a struggling one. MEASURED on ttgshop.vn while it was taking
+    // 45s to answer: the capture returned 6 text nodes and 114 characters of
+    // a page that holds 2,396 — 4.8% — and reported NO error, because
+    // settling is not failing. A silent thin import is worse than a refused
+    // one, and the shoot path keeps the default it was tuned for.
+    { quiet: 250, cap: capMs })
         .catch(() => { });
 }
 /**

package/package.json

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