Troubleshooting: the API said yes, the site says no

Резюме по-русски. Диагностика «ответ 200, а на сайте ничего»: сначала перечитать объект, потом открыть страницу браузером; таблица тихих отказов и чек-лист приёмки. Отдельно — правило «находка = замер + условия замера»: находка «siteMenu.level2 не работает» оказалась неверной, условия замера не записали. 2026-08-19 та же болезнь нашлась в ГЕЙТЕ: зелёный тест сторожил форму кода, а провода между двумя её концами не было — §7 про это.

Status: current · Verified: 2026-08-20, live calls + source measurements Owner: agent-api · Serves: GET /docs/troubleshooting Skill: vizen-troubleshoot

1. What you can do here

Tell apart three states that look identical from the client: a write rejected in substance, a value stored but read by no widget, and a change that is really on the page but invisible to your selector. This area also holds the acceptance checklist every storefront change goes through before the owner is told it is done. A 200 means the write was stored — not that the value is used.

2. Decide first — the order of diagnosis

Two checks, in this order, before you change anything:

The other order costs more: a lost value looks exactly like an ignored one.

⚠️ Level-1 selectors must pierce Shadow DOM. Level-1 own markup renders inside a shadow root (host div.vz-radius), and a plain document.querySelector does not see it. An empty result is not evidence that your markup is missing. A transferred folder (level 3) is real page DOM and needs none of this. Walk recursively:

const deepQuery = (sel, root = document) => {
  const hit = root.querySelector(sel); if (hit) return hit;
  for (const el of root.querySelectorAll('*'))
    if (el.shadowRoot) { const r = deepQuery(sel, el.shadowRoot); if (r) return r; }
  return null;
};

3. Silently ignored — the known cases

† carried over from the previous run's report and not re-measured on 2026-08-19 — reported, not proven. Anything you find that is not listed belongs here as a named case, with the configuration you measured on (§4).

Closed since the previous run, do not re-report: own markup and any other non-chrome block not sticking — props.position: "sticky" and vz-sticky both work since 2026-08-19 (§7); what survives is the narrower list in §3, and the answer is never position: fixed any more. Also closed: the resizer answering HEAD with 404. It answers HEAD and GET alike now — measured 2026-08-20, both 200 image/webp on api.vizen.shop and on the shop host. HEAD is a fine way to check that an image URL resolves. Also closed: "the page scope carries no list of products" (products[] is live — own-markup.md §2) and "the overflow axis never reaches the node that clips" (it does — row 1 of this table).

4. A finding is a measurement plus the conditions of the measurement

The rule this area exists to enforce, bought with a real mistake.

The claim. The previous run reported: "siteMenu.level2 is declared; with source: "categories" there are no dropdowns; the client gets a flat list of all 83 categories with no parents." It was filed as a platform defect, and vizen-webcoding-contract.json still lists it in silently_ignored. That entry is wrong and is superseded here.

What re-measurement showed. The menu block (id 2085) was configured source: "custom", level2: false, three hand-written items — a mode with no dropdowns by design. The run tested a switched-off feature and reported on the feature. A reversible experiment then set block 2085 to source: "categories", level2: true: the "Каталог" item rendered as <button> instead of <a> — an item becomes a button exactly when level2 && children.length > 0, so the children did arrive — and a click opened the panel with 82 sub-section links, tree complete, parents in place. The block was returned to custom / level2: false / three items and the rollback was verified.

The grain of truth is in the documentation, not the code. The widget schema says sub-sections drop down on hover; the panel opens on click, and a real mouse movement does not open it. The run checked hover, saw nothing, and condemned the mechanism. An error in a description costs what an error in code costs — this one sent a neighbouring chat into reworking a whole direction.

The rule. "X does not work" and "X does not open on hover with source: categories, level2: true" are different statements, and the first sends a whole direction into rework. Record the configuration you measured on: block id, the props as read back, the URL, the viewport width, hover or click. Of seven claims put through this review six held and one fell — and the one that fell was the only one derived from reading code instead of measuring.

5. Acceptance checklist

Run all of it before telling the owner you are done.

• [ ] the pages you did not touch are unchanged — the home page and two sections; curl shows the same data-vz-kit and none of your markup;
• [ ] the page opens by direct URL and by a link clicked inside the site — these are different code paths and scripts behave differently on each;
• [ ] after an in-site click: dropdowns open, modals open, timers run (platform handlers must re-initialise, and that is where they usually do not);
• [ ] the header holds at 375 / 520 / 700 / 900 / 1024 / 1440 / 1600, not only at your width; top of a sticky header = 0 while the page is scrolled;
• [ ] no position: fixed header and no hand-measured spacer anywhere in what you shipped — sticky works through props.position / vz-sticky since 2026-08-19, and a spacer is now a defect, not a workaround;
• [ ] no horizontal scrolling on the page body at any of those widths;
• [ ] the cart really accepts an item — press, watch the counter grow, check the button takes vz-state="in-cart";
• [ ] your text is present in the raw HTML: curl <page> | grep '<phrase>'. If it is not there, search engines never see it;
• [ ] images are served through the resizer (/w/<width>/webp/…), not as originals from storage.yandexcloud.net;
• [ ] the owner is told plainly what is a workaround — position: fixed, hand-counted spacers, prices frozen into own markup — and what is not;
• [ ] at least one screenshot from a real browser.

6. Measure, do not guess

Install a browser in the scratchpad and drive it. Status codes cannot tell you whether a dropdown opens or a header sticks: three edits out of eight in the previous run looked successful by status code and changed nothing on the site.

In that run 18% of steps went on browser checks, and they were the cheapest 18% of the build — every finding that survived review came from a measurement, and the single one that did not came from reading code instead. The same run spent 21% discovering what was possible and 12% redoing work after a change of course: 33% pure loss. Diagnosis is not the expensive part. Guessing is.

7. How this was verified

Live shop kiberpank.vizen.shop, 2026-08-19:

• storefront /neon-grid pulled and taken apart (683 KB of markup); menu, categories, products and chrome kit 2087 queried over the API;
• resizer measured on one URL: HEAD → 404, GET → 200 image/webp (superseded 2026-08-20 — see below);
• wrapper chain measured in a real browser through shadow roots — div.vz-box overflow: visible → div.vz-inner overflow: visible → div.vz-radius overflow: clip + shadow root (the chain still holds; what changed is that the last node is now switchable — see below);
• siteMenu.level2 re-measured by a reversible write to menu block 2085, 82 sub-section links counted in the open panel, block rolled back and the rollback checked;
• the filter. prefix is confirmed against api/catalog/catalog.proto:2768-2783: GetProductsRequest carries a nested Filter message with category_id, so the query parameter is filter.category_id and a bare category_id is not a field of the request;
• rows marked † in §3 come from the previous run and were not re-measured.

Re-measurement 2026-08-20 — three rows of §3 were stale, and one of the three was stale in the opposite direction from what the checklist assumed:

• the resizer and `HEAD`. curl -I and curl on the same live URL (/w/640/webp/vizen-prod-files/sunset/view/product/e3/83/…​.png) answer 200 `image/webp` both ways, on api.vizen.shop and on the shop host alike. The cause of the old 404 is in the source and is fixed: imgserve.go now registers mux.Head("/w/{width}/*", resize) next to the Get, because chi does not derive HEAD from GET. Gate: storefront/test/image-slicing.test.mjs · "HEAD у нарезчика зарегистрирован рядом с GET". The row is deleted, not edited: there is no silent failure left to describe;
• the `overflow` axis. SectionHtmlInline.tsx and SectionHtml.tsx both render the shadow host as clip={section.props?.overflow !== 'visible'}, so the axis reaches the node that actually clips. What remains true — and is now the row's content — is that the effective default for an html block is clip while /docs/widgets advertises "visible". Gate: storefront/test/wrapper-sticky-clip.test.mjs;
• the custom header. Was still not sticking at that hour, and not for the documented reason: a repo-wide search found htmlSticky written in storefront/src/islands/ZoneSections.tsx and read nowhere, and <SectionBox in eight places, none of which passed sticky. The branch existed; the wire did not. ⚠️ wrapper-sticky-clip.test.mjs was green through all of it, because it asserts the *shape* of the source, not that anything connects the two ends. A shape gate cannot see a disconnected wire — the §4 lesson, applied to gates instead of to findings.

The wire was built the same day, and the row in §3 was rewritten from the result. What changed, measured on rendered markup rather than on source shape:

• sectionSticky() is now asked by the section list (packages/sections/src/PageSections.tsx) and by the nested blocks of the columns widget, so props.position: "sticky" and vz-sticky both reach the band. The chrome-kit path goes through the same list, which is why a custom header in kit.top sticks;
• the order of branches inside wrapperFrameStyle() changed with it: the background layer used to set position: relative last and overwrote sticky, so a band with a background never stuck even where the wire existed. That one was invisible to every gate reading source text;
• three surfaces still do not ask, and §3 names each: the three chrome kinds (the wrapper does not run for them at all), vz-sticky inside a columns child, and the editor canvas;
• the new gate reads the style attribute of markup rendered through react-dom/server (storefront/test/wrapper-render.test.mjs), which is the only kind of gate that could have caught either defect.

8. Negations in this document (rule §3.9)

Every row of §3 is a negation — that is what the area is made of — so this table is the area's own regression list. A row without a gate is re-measured after each wave; a row with a gate falls the day the gate goes red.

⚠️ The lesson this table exists to carry. Two of the entries above are green gates that would not have caught the defect they guard: a gate that reads the source for a *shape* proves the shape, and a broken wire has the right shape at both ends. When a negation matters, re-measure it the way §4 demands — on the running thing, with the conditions written down — and treat the gate as a reminder, not as the proof.