similarbuild 0.3.3 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "similarbuild",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Visual migration framework for Claude Code — clone a live page, get a paste-ready WordPress/Elementor or Shopify section file, validated and auto-corrected.",
   "type": "module",
   "bin": {

package/templates/skills/sb-build-wp/SKILL.md

@@ -37,47 +37,81 @@ A single `.html` file written to `outputPath`. The file is a fragment — no `<h
 
 ## On Activation
 
-1. **Read the inputs.** Parse `inspection.json` (capture `sectionType`, `tokens`, `dom`, **`domLive`**, `pseudoElements`, `imgUrls`, **`hydratedHeader`**, **`hydratedFooter`**, and `screenshot` path) and `assets-map.json` (the URL → localPath / inline-SVG dictionary). If `fixHints` is given, also read `previousHtmlPath`.
+1. **Read the inputs.** Parse `inspection.json` (capture `sectionType`, `tokens`, `dom`, **`domLive`**, `pseudoElements`, `imgUrls`, **`hydratedHeader`**, **`hydratedFooter`**, and **`sectionCrops[]`**) and `assets-map.json` (the URL → localPath / inline-SVG dictionary). If `fixHints` is given, also read `previousHtmlPath`.
 
-   **§V03-3 — Section-level vision composition with ZERO-FABRICATION enforcement (REPLACES §V03-2).** The previous full-page screenshot approach (§V03-2) failed because page screenshots of 24000+ pixels tall get downscaled when read, making digits/labels unreadable — the LLM then completed gaps with plausible-but-wrong content (fabricated FAQ answers, wrong prices, hallucinated product counts, "old version of the site" pulled from training data).
+   **CANONICAL VISUAL INPUT = `sectionCrops[]`.** Do NOT read `inspection.screenshot` (full-page) — it's downscaled when loaded as image and digits become unreadable. The crops are HD-readable per section. Composer uses one crop per section it composes.
 
-   v0.3.3 fixes this with **section crops in native resolution**: `inspection.sectionCrops[]` carries one image per visual band (hero, products grid, FAQ, etc.) at the viewport's native width (390px on mobile). Each crop is HD-readable for the section it represents.
+   **§V03-4 — TERNARY section classification + ZERO-FABRICATION HARD ENFORCEMENT (replaces §V03-3).** Before composing ANY section, classify it into ONE of five categories. Pick the FIRST category that matches. Each category has a distinct compose recipe. Default = placeholder is FORBIDDEN; placeholder is only the last-resort for category (E).
 
    **Workflow when composing a body page** (anything NOT `--target-section=header|footer`):
 
-   1. **For each section you compose**, find the matching entry in `inspection.sectionCrops[]` by approximate bbox.y range and `sectionType` keyword. Read the crop image via Read tool — `Read({ file_path: cropEntry.path })`.
+   1. **Find the section's crop.** For each section you compose, find the matching `inspection.sectionCrops[]` entry by `bbox.y` proximity. Read the crop via `Read({ file_path: cropEntry.path })`.
 
-   2. **CRITICAL — Zero-fabrication rules. Treat these as hard contract:**
-      - **Literal text** (prices, review counts, button labels, headings, badge text, product names, percentages, dimensions): emit ONLY what you can read clearly in the crop AT NATIVE RESOLUTION. If you're not 100% sure of the exact characters (one digit looks like another, text is too small even in native, etc.), DO NOT GUESS — emit a `<!-- TODO: <visual description>, unreadable -->` comment + structural placeholder.
-      - **FAQ answers**: NEVER write FAQ answer bodies based on "plausible content for this brand". If `<details>`/`<summary>` accordion is visible in the crop but answers are collapsed, emit each `<summary>` text verbatim from the crop + empty `<div class="faq-a"><!-- TODO: answer body collapsed in source — open accordion or fetch live --></div>`. Same for reviews: if Loox/Yotpo widget appears as the band, emit empty `<div class="reviews-mount"><!-- TODO: third-party reviews widget, integrate at deploy time --></div>` — DO NOT compose fake reviews.
-      - **Product counts**: count cards/thumbs in the crop. If there are 4 product cards visible, emit exactly 4. Do not "round" to 3 because typical Shopify themes have 3.
-      - **Cross-validate every numeric literal against `inspection.domLive` text nodes.** Before emitting `<span>$29.00</span>`: grep `inspection.domLive` recursively for any text node containing `$29` or `29.00`. If found → safe to emit. If NOT found → emit `<!-- TODO: price "$29.00" read from crop but not present in DOM; verify -->` instead.
-      - **Site version awareness**: if the crop shows a banner like "Mother's Day Sale", "Black Friday Sale", limited-edition badges — emit them. Do NOT skip "because the site usually doesn't have this". The crop captured the LIVE state.
-      - **NEVER complete content based on knowledge of the public site.** You may have seen this URL in training data. That data is OLD. The crop is NEW. Crop wins, training data is irrelevant.
+   2. **Classify the section** into A / B / C / D / E:
 
-   3. **Emit real markup reflecting what the crop shows:**
-      - Counted gallery thumbs → emit each `<img>` with src resolved through `assetsMap.assets[url].localPath` matching URLs in `inspection.imgUrls`. If you can see 6 thumbs but `imgUrls` only has 3 matching URLs, emit 3 real `<img>` + 3 placeholders with `<!-- TODO: thumb N visible in crop, no src in inspection.imgUrls -->`.
-      - Literal price `$29.00` (cross-validated against DOM) → `<span class="price">$29.00</span> <s class="compare">$34.00</s>`.
-      - Banner with exact visible text → emit verbatim.
-      - Variant selectors: emit `<select>` with option list MATCHING WHAT'S VISIBLE. Inferred options (XS/XXXL not visible in crop) → emit only what's seen + `<!-- TODO: additional sizes likely available -->`.
-      - CTA: read the literal label text + observe button color. Emit with the right text + use color from `inspection.tokens.colors` for accent/primary.
+      **(A) IMAGE-BLOCK** — the section is dominated by a single `<img>` element. Detect by either:
+      - `inspection.domLive` (or `dom`) — the section's root node has a child `<img>` whose `bbox` covers ≥80% of the section's `bbox`, OR
+      - Wrapper class match: ancestor has class containing `product-info__image`, `image-with-text`, `hero-image`, `trust-badges`, `features-points`, `mothers-day`, `single-image`, `banner-image`, or similar "single asset" pattern.
+      - In Shopify Dawn/OS 2.0: **`<div class="product-info__image">` is THE canonical flag** — every match is an image-block.
 
-   4. **Hybridize DOM + vision (data source by field type):**
-      - **Texts/structure/counts** → crop image (truth of current state).
-      - **Hrefs** → `inspection.domLive` / `hydratedHeader` / `hydratedFooter` / `imgUrls` match by visible text. No match → `href="#"` + TODO.
-      - **Form action, method, hidden inputs** → ALWAYS DOM (never guess; broken submission else).
-      - **Image src** → `assetsMap.assets[url].localPath` resolved by visible alt or src pattern.
-      - **Computed style** → `inspection.tokens` + `domLive.computedStyle` for primary/accent colors and font tokens.
+      Recipe: **DO NOT reproduce the image's contents in HTML/CSS.** Emit:
+      ```html
+      <section class="es-{section-slug}">
+        <img src="{assetsMap.assets[url].localPath}" alt="{img.alt || section description}" loading="lazy" width="{img.width}" height="{img.height}" />
+      </section>
+      ```
+      Pull the URL from `inspection.imgUrls` matching the section's bbox / src pattern. If asset wasn't downloaded (failed extract or didn't appear in imgUrls), emit `<img src="" alt="..." data-todo="asset-missing">` + `<!-- TODO: image asset not in assetsMap (URL: …) — download manually -->`. No CSS reproduction. No SVG re-creation. No text "interpretation" of what's inside the image.
 
-   5. **Self-validation before submit:** before calling `build-wp.mjs write`, scan the composed HTML for fabrication signals:
-      - Every numeric literal `$NNNN` or `NNN reviews` MUST either (a) appear in a crop you actually read, or (b) be marked with a nearby TODO comment.
-      - Every FAQ `<div class="faq-a">` body MUST be non-empty ONLY if you literally read it from a crop. Empty bodies + TODO comment is the correct output when accordions are collapsed.
-      - Reviews widget bands → empty mount-div + TODO. Never fake review text.
-      If any violation found, REWRITE before submit. If you can't make it pass, return preflight error `composition-fabrication-detected` and let the orchestrator's Step 4j re-try with feedback.
+      **Examples from real feedback (everstride PDP)**: `mothers-day-new.svg` banner, `trust-badges-shipping.svg`, `features-points.svg`, `60-day-fit.svg` cards — all category (A).
 
-   6. **Hard-fail after 2 attempts.** The orchestrator (Step 4j) limits to 2 compose iterations. If iteration 2 still has fabrication signals, the orchestrator marks the page `❌` and ships a structural placeholder fragment with TODO comments — NEVER ship plausible-but-wrong content as "ready" or "partial".
+      **(B) PURE MARKUP** — the section is text + structured layout, no dominant image. Examples: FAQ accordion (`<details>/<summary>`), comparison tables (`<table>` with cells), pricing tiers, trust copy blocks, headings with paragraphs.
 
-   This contract enforces what the user explicitly asked for: "não pode me entregar algo diferente e se nao conseguir falha na 2 vez".
+      Recipe: READ the crop carefully + cross-validate every literal against `inspection.domLive` text nodes. Emit real semantic markup (`<table>`, `<dl>`, `<details>`, `<ul>` of `<li>`, etc.) that mirrors the live DOM structure.
+
+      **Cross-validation is MANDATORY for every literal**:
+      - Numeric (`$NN`, `NN reviews`, percentages, ratings): grep `inspection.domLive` recursively for a text node containing the exact substring. NOT found → emit `<!-- TODO: literal "$29.00" read from crop but not in DOM; verify -->` + placeholder.
+      - Headings/copy/labels: same rule. "What Customers Say", "All rights reserved", "Mix & Match Colors" — if not in DOM verbatim, do NOT emit.
+      - Counts: count items visible in crop AND cross-validate against `domLive` children of the container. If mismatch, prefer DOM count (DOM is authoritative for structure) + log discrepancy.
+
+      **(C) MIXED (image + text)** — the section has BOTH a meaningful image AND text content (heading + body paragraph + image side-by-side). Common Shopify pattern: `<images-with-text-scrolling>` custom element.
+
+      Recipe: emit `<section>` with `<img>` (rule A for the image part — use real asset URL when available) + `<h*>` heading + `<p>` paragraph(s) literal from crop, cross-validated. Do NOT collapse to image-only or text-only — preserve both.
+
+      **(D) WIDGET-RENDERED** — third-party widget (Loox reviews, "you may also like" carousel, Instagram feed) where the crop SHOWS the widget already rendered with content (reviews with names + photos + stars + quotes; product cards with prices + titles).
+
+      Recipe: READ the crop and emit real markup for each visible card/item. Cross-validate against DOM when widget exposes content as JSON-LD or hidden HTML. Mark container with `data-source="widget-name"` so the deploy team knows where to integrate the real widget later. **Do NOT emit empty mount-div when content is visible.** The "deploy time placeholder" excuse is ONLY for (E).
+
+      **(E) WIDGET-EMPTY / OPAQUE** — the crop is blank, only shows "Loading..." text, or the section is completely unreadable (zero text visible, no images, no structure). Last resort.
+
+      Recipe: emit STRUCTURAL placeholder (heading from DOM if available + `<div class="placeholder-grid">` with N visual placeholder-cards) + `<!-- TODO: <widget-name or section-description> — content not visible in crop, integrate at deploy -->`. Mount-div alone (empty `<div>`) is FORBIDDEN — placeholder must have visible structure so the deployed page is not visually broken.
+
+   2.5. **CARD-COUNT cross-validation (V03-5)**. When the section is a grid/carousel of repeating cards (products, reviews, trust badges, gallery thumbs, testimonial photos), the crop may only show the first row OR the first few items of a scroll-x carousel. Composer MUST count cards from `inspection.domLive` (or `inspection.dom`) recursively, NOT just from the crop. Recipe:
+      - Find the section's root node in domLive (by bbox.y match or sectionType).
+      - Walk children, count direct repeat-pattern items: `.product-card`, `.review-card`, `.feature-card`, `<li>` inside `<ul>` carousel, `[role="listitem"]`, etc.
+      - If DOM count > crop visible count → emit DOM count items, with `<img>` placeholder + literal text (cross-validated) for the items visible in crop, and `<img>` placeholder + `<!-- TODO: card N text below the fold -->` for items beyond crop.
+      - This fixes bugs 3.4 (home only 3 cards), 3.6 (trust badges only 2 of 4), 4.1 (PDP gallery only 1 thumb of 6), 6.1 (collection only 1 of 3 products).
+      - **NEVER emit fewer items than DOM has.** Crop visibility is sample, DOM is authority for structure.
+
+   3. **Hybridize sources by field type** (applies to B, C, D):
+      - **Texts/structure/counts** → crop, cross-validated against DOM.
+      - **Hrefs** → `inspection.domLive` / `hydratedHeader` / `hydratedFooter` / `imgUrls` by matching visible link text. No match → `href="#"` + TODO.
+      - **Form action/method/hidden inputs** → ALWAYS DOM (never guess; broken submission else).
+      - **Image src** → `assetsMap.assets[url].localPath` by alt/src pattern matching imgUrls.
+      - **Computed style** → `inspection.tokens` + `domLive.computedStyle`.
+
+   4. **Self-validation BEFORE calling `build-wp.mjs write`** — scan composed HTML for fabrication signals:
+      - Every numeric/price literal must either appear in `inspection.domLive` text nodes OR have a nearby TODO comment.
+      - Every `<h*>` / heading text must appear in DOM verbatim OR have TODO.
+      - Every `<p>` text > 30 chars must appear in DOM verbatim OR have TODO.
+      - Every FAQ `<div class="faq-a">` body MUST be either (a) empty + TODO when accordion was closed, OR (b) verbatim from crop where accordion was open.
+      - Image-block sections (A) MUST NOT contain SVG reproductions or CSS-styled `<div>` mimicking the image — they MUST be `<img>` + nothing else inside the section.
+      If any violation → REWRITE before submit. If can't pass after 1 rewrite, return preflight error `composition-fabrication-detected` for orchestrator Step 4j retry.
+
+   5. **Hard-fail after 2 attempts.** Orchestrator (Step 4j) caps at 2 compose iterations. 2nd iteration still flagged → page goes to **❌** with TODO-only fragment shipped (not as "ready" or "partial"). NEVER plausible-but-wrong shipped as warning.
+
+   6. **NEVER complete content from training data.** You may have seen this URL during training. That data is OLD. The crop is NEW. Crop wins. Training data is IRRELEVANT — never fill gaps with "what this site probably has".
+
+   This contract enforces the user's hard requirement: "não pode me entregar algo diferente e se não conseguir falha na 2 vez."
 
    **§V03-1 — Use `domLive` as the canonical body tree when present.** When `inspection.domLive` is non-null, it holds the live-walker snapshot taken BEFORE Cap A substituted `dom[]` with the shadow-flattened tree. The flattened `dom[]` carries `bbox={0,0,0,0}` and empty `computedStyle` because parseHTMLUnsafe returns a detached doc — it's structurally rich (gallery imgs, custom-element children) but useless for layout. The composer needs real bboxes, real `computedStyle.background`, real heights. Always prefer `inspection.domLive` for body section composition (bbox, computedStyle, hero detection, section ordering). Use `inspection.dom` only when `domLive === null` (page had no shadow roots — flatten didn't fire) or when you specifically need shadow-flattened content like a PDP gallery (consult `dom` for image-rich PDP nodes, but use `domLive` for the surrounding layout).
 
@@ -140,24 +174,118 @@ A single `.html` file written to `outputPath`. The file is a fragment — no `<h
 
 When `--target-section=header` or `--target-section=footer` is passed AND the corresponding `inspection.hydratedHeader` / `inspection.hydratedFooter` is non-null, follow this composition recipe instead of the generic A-H pattern lookup:
 
-**Footer recipe** (when `hydratedFooter` present):
+**Footer recipe** (when `hydratedFooter` present) — v0.3.5 rewrite:
+
+**Composition order = DOM order of `hydratedFooter.html`.** Walk the raw HTML once to capture the visual sequence (e.g. brand → newsletter → menu columns → Need Help → social → payments → copyright). DO NOT invent an order that differs from the source — the live site's order is the canonical reference.
 
-1. **Outer shell.** `<footer class="es-footer">` with reset + `box-sizing: border-box` + the page background-color taken from `inspection.tokens.colors.background` (or fallback `#fafafa`).
-2. **Grouping.** Split `hydratedFooter.links` into clusters by their adjacent heading in `hydratedFooter.headings`. Order of headings reflects the live DOM order. For each heading: emit a column with `<p class="footer__col-title">{heading.text}</p>` followed by `<ul>` of `<li><a href>` from the links bucketed under that heading.
-   - Heuristic for bucketing: walk `hydratedFooter.html` once (in your head, you have the raw outerHTML in `hydratedFooter.html` if needed) — links that appear AFTER a heading and BEFORE the next heading belong to that heading. If you can't disambiguate, fall back to grouping by `href` prefix patterns (`/policies/` → "More Information", `/products/` → "Collections", `/pages/` → split by name).
-3. **Newsletter.** If `hydratedFooter.forms[]` is non-empty AND `hydratedFooter.inputs[]` contains an `email`-typed input, emit a real `<form action="{form.action}" method="{form.method}">` with the email input, preserving `name`, `placeholder`, `required`, `aria-label`. Hidden inputs (`type=hidden`) are preserved verbatim — they're typically Shopify form-type tokens. Add a submit `<button type="submit">` even if not in the source.
-4. **Social media.** Detect social links by `href` matching `/facebook|instagram|tiktok|youtube|x\.com|twitter|pinterest/`. Group in a separate `<ul class="footer__social">` with inline SVG icons (you can ship the standard FB/IG icons from the bundled patterns). Skip if no matches.
-5. **Payment icons.** Detect by `hydratedFooter.images[]` with `alt` matching `/amazon|visa|mastercard|amex|apple pay|google pay|discover|diners|shop pay|paypal/i` — emit those as a `<ul class="footer__payments">` with `<img>` referencing the `assetsMap` (resolve src via the standard pipeline). If `images[]` is empty but you'd expect them, fall back to text labels.
-6. **Copyright.** If any link or heading text matches `© YEAR, Brand.`, preserve verbatim at the bottom.
-7. **NO image-slice fallback.** When hydrated data is present, never compose a single `<img>` of the footer. The hydrated payload gives everything needed for real markup.
+Use `hydratedFooter.blocks[]` (new in v0.3.5) as primary structured data — each block has `{heading, paragraphs[], links[], mailtos[]}` already grouped per source heading.
 
-**Header recipe** (when `hydratedHeader` present):
+1. **Outer shell.** `<footer class="es-footer">` with reset + `box-sizing: border-box` + background from `inspection.tokens.colors.background` (fallback `#fafafa`).
+
+2. **Brand row (top).** When `hydratedFooter.images[]` includes a logo-looking image (alt matching brand name, or first image of the footer), emit `<a class="es-footer__brand" href="/"><img src="{assetsMap.localPath}"></a>`. Immediately below, if `hydratedFooter.paragraphs[0]` exists AND is long enough to be the brand description (typically >50 chars, sits ABOVE the column area in the live source), emit `<p class="es-footer__brand-desc">{paragraphs[0] verbatim}</p>`. This is the "Socks can be more powerful..." copy in everstride — DO NOT skip.
+
+3. **Newsletter (after brand description).** If `hydratedFooter.forms[]` non-empty AND `inputs[]` contains an `email`-typed input, emit `<form action="{form.action}" method="{form.method}">` with email input (preserve `name`, `placeholder`, `required`, `aria-label`) + all hidden inputs verbatim + `<button type="submit">`. **Position: directly below brand desc, ABOVE the menu columns.** Newsletter is high-conversion CTA — keep it where the live placed it.
+
+4. **Menu columns side-by-side (NOT stacked).** Take `hydratedFooter.blocks[]` filtered to those with `links.length >= 2` (menu-style blocks). Emit them as a grid:
+   ```css
+   .es-footer__cols.es-footer__cols { 
+     display: grid; 
+     grid-template-columns: repeat(2, minmax(0, 1fr)); 
+     gap: 24px; 
+   }
+   @media (min-width: 750px) { 
+     .es-footer__cols.es-footer__cols { grid-template-columns: repeat(3, minmax(0, 1fr)); } 
+   }
+   ```
+   For each menu block: emit column with `<p class="es-footer__col-title">{block.heading.text verbatim}</p>` + `<ul>` of `<li><a href="{link.href}">{link.text verbatim}</a></li>` from `block.links`. **NEVER stack vertically on mobile** — at least 2 columns side-by-side is the canonical layout, otherwise footer becomes an absurd long vertical strip (bug 2.4).
+
+5. **Info blocks (Need Help? and similar).** Blocks with `paragraphs.length >= 1` AND `links.length < 2` are info-text blocks. For each: emit column with heading + `block.paragraphs[]` as `<p>` verbatim + `mailto:` links from `block.mailtos[]` as `<a href="mailto:{email}">{email}</a>`. This captures "Need Help? + Have a question? Email us at info@... + Our friendly support team is available 24/7..." (bug 2.5b — was emitting only heading without paragraphs).
+
+6. **Social icons.** Detect from `hydratedFooter.links` filtered by `href` matching `/facebook|instagram|tiktok|youtube|x\.com|twitter|pinterest/i`. Emit as `<ul class="es-footer__social">` with inline SVG icons (use `hydratedFooter.inlineSvgs[]` matching parent class containing `social`; fall back to bundled FB/IG inline SVG patterns). Position: between menu columns and payment icons (or wherever the source places them).
+
+7. **Payment icons.** Detect by EITHER:
+   - `hydratedFooter.images[]` with `alt` matching `/amazon|visa|mastercard|amex|apple pay|google pay|discover|diners|shop pay|paypal/i`, OR
+   - `hydratedFooter.inlineSvgs[]` with `ariaLabel`, `title`, or `parentClass` matching the same patterns, OR
+   - `hydratedFooter.inlineSvgs[]` where `parentClass` contains `payment-icons` / `footer__payment`.
+   Emit as `<ul class="es-footer__payments">` with `<img>` (resolved via assetsMap) OR inline SVG verbatim. If none of these match BUT you can see payment icons in the section crop, emit `<!-- TODO: payment icons visible in crop but not capturable from DOM -->`. NEVER skip the payment row when source had it (bug 2.1).
+
+8. **Copyright.** Capture `© YEAR, Brand.` verbatim from `hydratedFooter.html` (typically last `<p>` in the footer matching `/^(©|copyright)/i`). Emit `<p class="es-footer__copyright">© 2026, Everstride.</p>` — **verbatim only, NEVER add "All rights reserved" or any other plausible-sounding suffix** (bug 2.5a fabrication regression).
+
+9. **Cross-validate every literal** before emit: every block heading, every link text, every paragraph, every copyright text MUST appear verbatim in `hydratedFooter.html`. Validator (`build-wp.mjs validate --inspection-path`) will catch fabrications; pre-validate yourself to avoid rework.
+
+10. **NO image-slice fallback.** When `hydratedFooter` is present, never compose a single `<img>` of the footer. Hydrated payload always provides enough for real markup.
+
+**Header recipe** (when `hydratedHeader` present) — v0.3.5 rewrite:
+
+1. **Announcement bar FIRST (when `inspection.hydratedAnnouncementBar` is non-null).** This is captured separately in v0.3.5 — typically a `<aside>` sibling above the `<header>` carrying promotional text ("Mother's Day Sale", "Free Shipping over $X", etc.). Emit as the very first element of `clean/global/header.html`:
+   ```html
+   <div class="es-announcement-bar.es-announcement-bar">
+     {hydratedAnnouncementBar.text verbatim}
+   </div>
+   ```
+   With CSS giving it the pink/promo background read from the crop. **NEVER skip the announcement bar** when it was captured — bug 1.1 (banner not in header) AND bug 3.1 (banner ended up inline in body) both trace to this being omitted. Also remove from per-page body via stripper.
+
+2. **Outer shell.** `<header class="es-header">` below the announcement bar.
+
+3. **Layout: grid with 3 zones (centered logo).** Default mobile + desktop:
+   ```css
+   .es-header.es-header { 
+     display: grid; 
+     grid-template-columns: auto 1fr auto; 
+     align-items: center; 
+     padding: 12px 16px;
+   }
+   .es-header.es-header > .es-header__left { justify-self: start; }
+   .es-header.es-header > .es-header__brand { justify-self: center; }
+   .es-header.es-header > .es-header__right { justify-self: end; }
+   ```
+   This guarantees the brand stays VISUALLY centered regardless of how many icons are in left/right clusters — fixes bug 1.3 (logo descentralizada).
+
+4. **Brand (center).** If `hydratedHeader.images[]` includes a logo-looking image (alt matching brand name OR class containing `logo`/`brand`), emit `<a class="es-header__brand" href="/"><img src="{assetsMap.localPath}" alt="{brand}"></a>`. If brand is text-only (no img), emit `<span class="es-header__brand">{brand-name}</span>`.
+
+5. **Left cluster: hamburger + search.** On mobile (`@media (max-width: 749px)`), emit `<div class="es-header__left">` with a `<button>` hamburger trigger (aria-controls a drawer) + a `<button>` search trigger. On desktop, replace hamburger with horizontal nav links (rule 7).
+
+6. **Right cluster: utility icons.** Links/buttons matching `/account|cart|search/` go into `<div class="es-header__right">` with proper SVG icons (use `hydratedHeader.inlineSvgs[]` matching parent class containing `account|cart|search`, OR fall back to bundled icon set).
+
+7. **Desktop nav (visible only ≥750px).** Take category links from `hydratedHeader.links` filtered by hrefs matching `/products|collections|categories|shop/` (top-level shop nav). Emit as `<nav class="es-header__nav-desktop"><ul>{links}</ul></nav>` between brand and right cluster, with `display: none` on mobile.
+
+8. **Mobile drawer (V03-5 corrected UX).** Bug 1.2 — previous output had logo inside drawer + no overlay. Correct UX:
+   ```html
+   <div class="es-drawer-backdrop" data-drawer-backdrop hidden>
+     <div class="es-drawer" data-drawer role="dialog" aria-modal="true">
+       <button class="es-drawer__close" aria-label="Close menu" data-drawer-close>✕</button>
+       <nav>
+         <ul class="es-drawer__nav">
+           <!-- category links from hydratedHeader.links, NO LOGO inside -->
+         </ul>
+       </nav>
+       <!-- Optional: account link / login at footer of drawer if source has it -->
+     </div>
+   </div>
+   ```
+   CSS:
+   ```css
+   .es-drawer-backdrop.es-drawer-backdrop[hidden] { display: none; }
+   .es-drawer-backdrop.es-drawer-backdrop { 
+     position: fixed; inset: 0; 
+     background: rgba(0,0,0,.5); 
+     z-index: 9999; 
+   }
+   .es-drawer.es-drawer { 
+     position: absolute; top: 0; left: 0; bottom: 0; 
+     width: min(85vw, 360px); 
+     background: #fff; 
+     padding: 24px 20px; 
+     overflow-y: auto;
+   }
+   .es-drawer__close.es-drawer__close { 
+     position: absolute; top: 12px; right: 12px; 
+     background: none; border: 0; font-size: 24px; 
+   }
+   ```
+   JS: vanilla toggle on hamburger click. **NO LOGO inside drawer** — logo is in the header shell, not duplicated. **Backdrop overlay is mandatory** — drawer with no backdrop is the v0.3.x bug.
 
-1. **Outer shell.** `<header class="es-header">` with sticky position if the page tokens indicate so.
-2. **Promo bar.** If any link's text matches a promotional pattern (`/sale|discount|free|% off/i`) OR `hydratedHeader.headings[]` contains a short standalone heading at the top, emit `<div class="es-header__promo">{text}</div>`.
-3. **Brand.** If `hydratedHeader.images[]` includes one with `alt` matching the brand name (derived from URL or generic `logo`), emit `<a class="es-header__brand" href="/">` with that `<img>`.
-4. **Nav.** Take `hydratedHeader.links` filtered to category-looking hrefs (`/products/...`, `/collections/...`, top-level pages). Emit as `<nav><ul>{links}</ul></nav>`. On mobile (`@media (max-width: 749px)`), collapse into a `<details><summary aria-label="Menu">` drawer — keep all category links inside.
-5. **Utility icons.** Links with text "Open search", "Account", "Cart" (or matching hrefs `/search`, `/account`, `/cart`) get rendered as a right-side cluster of icon buttons.
+9. **Cross-validate every literal** (brand text, link texts, announcement bar text) against `hydratedHeader.html` / `hydratedAnnouncementBar.html` before emit. Validator catches fabrications.
 
 **Output contract for header/footer:**
 - Markup includes a top comment `<!-- sb-build-wp: composed from hydrated snapshot (V03-0a) -->`.

package/templates/skills/sb-build-wp/references/wp-build-rules.md

@@ -51,7 +51,17 @@ The Elementor + active theme stack frequently injects `!important` on these prop
 - `font-weight` — set on `h1..h6`, `body`
 - `color` — set on links via `.elementor a`, on body via theme
 
-Use `!important` ONLY on these four properties when they appear on critical text. Do NOT spray `!important` everywhere — overuse turns debugging into a nightmare. Specifically: do NOT `!important` margins, paddings, widths, heights, backgrounds, transforms, transitions.
+### v0.3.5 — Expanded property list (after real-world "tudo liso no WordPress" bug 3.4):
+
+The above 4-property list was insufficient — when output was published in WordPress, the products grid and other card-based layouts came out "tudo liso" (no border-radius, no shadow, no gaps). The Elementor theme stack also normalizes/overrides these visual properties on `*` selectors. Add `!important` ALSO to:
+
+- `border-radius` — on cards, buttons, image containers (themes flatten cards otherwise)
+- `box-shadow` — on cards and elevated elements
+- `background-color` — on color-bearing blocks (`.es-card`, `.es-cta`, `.es-banner`) when the visual identity depends on it
+- `gap` (and `column-gap`, `row-gap`) — on grid/flex containers (themes that reset child margins also reset gaps)
+- `padding` — on card-like containers and section blocks where the live padding is visually critical
+
+Apply via the same chained-scope pattern (`.es-card.es-card { border-radius: 12px !important; }`). Still DO NOT spray `!important` on margin, width, height, transforms, transitions — those rarely conflict with theme.
 
 ## Reset universal
 

package/templates/skills/sb-build-wp/scripts/build-wp.mjs

@@ -78,7 +78,7 @@ function findAll(re, str) {
   return out
 }
 
-function validateHtml(html) {
+function validateHtml(html, inspection = null) {
   const errors = []
   const warnings = []
   const info = []
@@ -228,6 +228,103 @@ function validateHtml(html) {
     fabricationRisks.push({ section: m[1].trim(), reason: m[2].trim() })
   }
 
+  // 13. §V03-4 fabrication detector — when inspection JSON is provided,
+  // cross-validate every literal text in the composed HTML against the
+  // inspection's text corpus (domLive + dom + hydratedHeader.html +
+  // hydratedFooter.html). Literals that don't appear ANYWHERE in the
+  // inspection corpus are flagged as fabrications.
+  //
+  // Detected literal types:
+  //   - prices/money: $\d+(.\d{2})? or \d+\.\d{2}\b
+  //   - countdown phrases: \d+(?:,\d{3})*\s*(reviews|customers|women|sold|pairs|...)
+  //   - headings text content (h1-h6 + p.bold-like)
+  //   - meaningful paragraph text >30 chars
+  //
+  // Findings emit error `composition-fabrication-detected` so the orchestrator
+  // (Step 4j) can re-trigger composition with feedback.
+  const fabricationFindings = []
+  if (inspection && typeof inspection === 'object') {
+    const corpus = buildInspectionCorpus(inspection)
+    const looseCorpus = corpus
+      .toLowerCase()
+      .replace(/\s+/g, ' ')
+      .replace(/[‘’]/g, "'")
+      .replace(/[“”]/g, '"')
+      .replace(/[—–-]+/g, '-')
+    // strip TODO-commented regions so they don't get re-scanned
+    const htmlBody = html.replace(/<!--[\s\S]*?-->/g, '')
+    // (a) money literals
+    const moneyRe = /\$\d{1,5}(?:\.\d{2})?/g
+    const moneyHits = new Set()
+    for (let m = moneyRe.exec(htmlBody); m; m = moneyRe.exec(htmlBody)) moneyHits.add(m[0])
+    for (const lit of moneyHits) {
+      if (!corpusHas(looseCorpus, lit)) {
+        fabricationFindings.push({
+          kind: 'money',
+          literal: lit,
+          severity: 'high',
+          message: `Money literal "${lit}" not found in inspection corpus (domLive/dom/hydratedHeader/hydratedFooter)`,
+        })
+      }
+    }
+    // (b) count phrases like "19,479 Reviews", "240,000+ Women", "1M+ Sold"
+    const countRe = /\b(\d[\d,]{1,9}\+?)\s+(reviews?|customers?|women|sold|pairs?|orders?|stars?|users?|clinicians?|five-star|verified)\b/gi
+    const countHits = new Set()
+    for (let m = countRe.exec(htmlBody); m; m = countRe.exec(htmlBody)) countHits.add(m[0])
+    for (const lit of countHits) {
+      if (!corpusHas(looseCorpus, lit)) {
+        fabricationFindings.push({
+          kind: 'count',
+          literal: lit,
+          severity: 'high',
+          message: `Count phrase "${lit}" not found in inspection corpus`,
+        })
+      }
+    }
+    // (c) headings — text content of h1..h6
+    const headingRe = /<h[1-6][^>]*>([\s\S]*?)<\/h[1-6]>/gi
+    const headingHits = new Set()
+    for (let m = headingRe.exec(htmlBody); m; m = headingRe.exec(htmlBody)) {
+      const txt = m[1].replace(/<[^>]+>/g, '').trim()
+      if (txt.length >= 3 && txt.length <= 120) headingHits.add(txt)
+    }
+    for (const lit of headingHits) {
+      if (!corpusHas(looseCorpus, lit)) {
+        fabricationFindings.push({
+          kind: 'heading',
+          literal: lit,
+          severity: 'high',
+          message: `Heading "${lit}" not found in inspection corpus`,
+        })
+      }
+    }
+    // (d) long paragraphs (>30 chars) — text content of <p>
+    const paraRe = /<p[^>]*>([\s\S]*?)<\/p>/gi
+    const paraHits = new Set()
+    for (let m = paraRe.exec(htmlBody); m; m = paraRe.exec(htmlBody)) {
+      const txt = m[1].replace(/<[^>]+>/g, '').trim()
+      if (txt.length >= 30 && txt.length <= 400) paraHits.add(txt)
+    }
+    for (const lit of paraHits) {
+      if (!corpusHas(looseCorpus, lit)) {
+        fabricationFindings.push({
+          kind: 'paragraph',
+          literal: lit.slice(0, 80) + (lit.length > 80 ? '…' : ''),
+          severity: 'medium',
+          message: `Paragraph "${lit.slice(0, 80)}…" not found in inspection corpus`,
+        })
+      }
+    }
+    if (fabricationFindings.length > 0) {
+      errors.push({
+        rule: 'composition-fabrication-detected',
+        severity: 'high',
+        message: `§V03-4 fabrication-detector found ${fabricationFindings.length} literal(s) not present in inspection corpus. The composer should re-read the section crops and either remove the fabricated literals OR replace with TODO comments.`,
+        findings: fabricationFindings,
+      })
+    }
+  }
+
   return {
     passed: errors.length === 0,
     errorCount: errors.length,
@@ -236,9 +333,62 @@ function validateHtml(html) {
     warnings,
     info,
     fabricationRisks,
+    fabricationFindings,
   }
 }
 
+// §V03-4 — Build a single lowercased text corpus from all inspection text
+// sources for fabrication cross-validation. Includes:
+//   - domLive (preferred) / dom: every node.text + node.attrs.alt
+//   - hydratedHeader.html, hydratedFooter.html (raw outerHTML strings)
+function buildInspectionCorpus(inspection) {
+  const parts = []
+  function walkText(arr) {
+    if (!arr) return
+    const stack = Array.isArray(arr) ? [...arr] : [arr]
+    while (stack.length) {
+      const n = stack.pop()
+      if (!n || typeof n !== 'object') continue
+      if (typeof n.text === 'string' && n.text.trim()) parts.push(n.text)
+      if (n.attrs && typeof n.attrs === 'object') {
+        if (typeof n.attrs.alt === 'string') parts.push(n.attrs.alt)
+        if (typeof n.attrs['aria-label'] === 'string') parts.push(n.attrs['aria-label'])
+        if (typeof n.attrs.title === 'string') parts.push(n.attrs.title)
+      }
+      if (Array.isArray(n.children)) for (const c of n.children) stack.push(c)
+    }
+  }
+  walkText(inspection.domLive)
+  if (!inspection.domLive) walkText(inspection.dom)
+  if (inspection.hydratedHeader && typeof inspection.hydratedHeader.html === 'string') {
+    parts.push(inspection.hydratedHeader.html.replace(/<[^>]+>/g, ' '))
+  }
+  if (inspection.hydratedFooter && typeof inspection.hydratedFooter.html === 'string') {
+    parts.push(inspection.hydratedFooter.html.replace(/<[^>]+>/g, ' '))
+  }
+  return parts.join(' \n ')
+}
+
+// Loose comparison: literal appears in the corpus with whitespace and
+// punctuation normalization. Handles "$29.00" matching "$ 29.00" etc.
+function corpusHas(looseCorpusLower, literal) {
+  if (!literal) return true
+  const needle = literal
+    .toLowerCase()
+    .replace(/\s+/g, ' ')
+    .replace(/[‘’]/g, "'")
+    .replace(/[“”]/g, '"')
+    .replace(/[—–-]+/g, '-')
+    .trim()
+  if (!needle) return true
+  // direct substring
+  if (looseCorpusLower.includes(needle)) return true
+  // also try removing all whitespace (handles "$29 .00" vs "$29.00")
+  const compact = needle.replace(/\s+/g, '')
+  const compactCorpus = looseCorpusLower.replace(/\s+/g, '')
+  return compactCorpus.includes(compact)
+}
+
 // --- preflight ----------------------------------------------------------------
 //
 // Pre-dispatch checklist. The composer is creative — it picks patterns and
@@ -425,8 +575,21 @@ async function main() {
     } catch (err) {
       fail(`validate: cannot read ${path}: ${err.message}`, 1)
     }
-    log(values.verbose, `validating ${path} (${html.length} bytes)`)
-    const report = validateHtml(html)
+    // §V03-4 fabrication detector — when --inspection-path is passed, load
+    // the inspection JSON and cross-validate composed HTML literals
+    // against the inspection text corpus. Without --inspection-path, the
+    // fabrication check is skipped (back-compat for older callers).
+    let inspection = null
+    if (values['inspection-path']) {
+      try {
+        const insRaw = await readFile(resolve(values['inspection-path']), 'utf8')
+        inspection = JSON.parse(insRaw)
+      } catch (err) {
+        log(values.verbose, `validate: could not load --inspection-path: ${err.message}`)
+      }
+    }
+    log(values.verbose, `validating ${path} (${html.length} bytes${inspection ? ', with fabrication check' : ''})`)
+    const report = validateHtml(html, inspection)
     process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
     process.exit(report.passed ? 0 : 3)
   }

package/templates/skills/sb-inspect-live/scripts/inspect-live.mjs

@@ -259,8 +259,32 @@ async function main() {
         }
         return best?.el || null
       }
+      // §V03-5 — announcement bar (promo bar on top of the page,
+      // typically <aside> sibling above the <header>). Common in e-commerce
+      // ("Mother's Day Sale", "Free Shipping over $X", etc.). Captured as
+      // separate snapshot so the composer can compose it as part of the
+      // global chrome (above the header) — not as inline body content of
+      // the home page.
+      function pickAnnouncementBar() {
+        const candidates = document.querySelectorAll(
+          'aside[class*="announcement"], [class*="announcement-bar"], [class*="promo-bar"], [class*="shopify-section-group-header-group"][class*="announcement"], aside[class*="shopify-section-group-header"]',
+        )
+        let best = null
+        for (const el of candidates) {
+          const r = el.getBoundingClientRect()
+          if (r.height < 20 || r.height > 200) continue
+          // must be near top of page
+          if (Math.abs(r.y + window.scrollY) > 200) continue
+          const txt = (el.textContent || '').trim()
+          if (!txt) continue
+          const score = txt.length / 10 + (r.width >= 320 ? 5 : 0)
+          if (!best || score > best.score) best = { el, score }
+        }
+        return best?.el || null
+      }
       const footer = pickFooter()
       const header = pickHeader()
+      const announcement = pickAnnouncementBar()
       window.__sbHydratedFooter = footer
         ? {
             html: footer.outerHTML,
@@ -289,6 +313,29 @@ async function main() {
             })(),
           }
         : null
+      window.__sbHydratedAnnouncementBar = announcement
+        ? {
+            html: announcement.outerHTML,
+            text: (() => {
+              // Strip inline <script>/<style> tags before reading text —
+              // Shopify themes inline CSS variables and JS at the top of
+              // the announcement-bar section, which would otherwise leak
+              // into the "text" field as garbage.
+              const clone = announcement.cloneNode(true)
+              clone.querySelectorAll('script,style').forEach((n) => n.remove())
+              return (clone.textContent || '').replace(/\s+/g, ' ').trim()
+            })(),
+            bbox: (() => {
+              const r = announcement.getBoundingClientRect()
+              return {
+                x: Math.round(r.x + window.scrollX),
+                y: Math.round(r.y + window.scrollY),
+                w: Math.round(r.width),
+                h: Math.round(r.height),
+              }
+            })(),
+          }
+        : null
     })
 
     // Return to the top before layout reads. content-visibility:auto on
@@ -453,6 +500,84 @@ async function main() {
         const slug = (cls || tag).replace(/[^a-z0-9-]/gi, '-').toLowerCase().slice(0, 32)
         return slug || 'section'
       }
+
+      // §V03-4 image-block detection. A section is an image-block when
+      // its visible content is dominated by a single <img>: either by
+      // bbox coverage (img takes ≥80% of section area) OR by a known
+      // wrapper-class pattern (Shopify Dawn / OS 2.0 themes use specific
+      // wrapper classes like `product-info__image` to delimit a region
+      // whose entire visual content is one CDN-hosted SVG/PNG/JPG asset).
+      // The composer (sb-build-wp §V03-4 rule A) treats image-block
+      // sections as "download asset + emit <img src>" — NEVER tries to
+      // reproduce the visual contents in HTML/CSS.
+      const IMAGE_BLOCK_WRAPPER_PATTERNS = [
+        /product-info__image/i,
+        /image-with-text/i,
+        /\bhero-image\b/i,
+        /\btrust-badges\b/i,
+        /\bfeatures-points\b/i,
+        /\bmothers?-day\b/i,
+        /\bsingle-image\b/i,
+        /\bbanner-image\b/i,
+        /\bguarantee-card\b/i,
+        /\bbest-fit-size-chart\b/i,
+      ]
+      function classifyAsImageBlock(node) {
+        if (!node || typeof node !== 'object') return null
+        const sectionBbox = node.bbox
+        if (!sectionBbox || !sectionBbox.h || !sectionBbox.w) return null
+        const sectionArea = sectionBbox.h * sectionBbox.w
+        if (sectionArea <= 0) return null
+        // Match by wrapper-class pattern on the node itself OR any
+        // descendant (the wrapper might be a child of the section root).
+        function findClassMatch(n) {
+          if (!n || typeof n !== 'object') return null
+          if (Array.isArray(n.classes)) {
+            for (const cls of n.classes) {
+              for (const pat of IMAGE_BLOCK_WRAPPER_PATTERNS) {
+                if (pat.test(cls)) return cls
+              }
+            }
+          }
+          if (Array.isArray(n.children)) {
+            for (const c of n.children) {
+              const m = findClassMatch(c)
+              if (m) return m
+            }
+          }
+          return null
+        }
+        const classMatch = findClassMatch(node)
+        // Find the largest <img> descendant by bbox area.
+        let bestImg = null
+        function findBiggestImg(n) {
+          if (!n || typeof n !== 'object') return
+          if (n.tag === 'img' && n.bbox && n.bbox.h > 0 && n.bbox.w > 0) {
+            const a = n.bbox.h * n.bbox.w
+            if (!bestImg || a > bestImg.area) {
+              const src = (n.attrs && (n.attrs.src || n.attrs.srcset)) || ''
+              bestImg = { area: a, bbox: n.bbox, src }
+            }
+          }
+          if (Array.isArray(n.children)) {
+            for (const c of n.children) findBiggestImg(c)
+          }
+        }
+        findBiggestImg(node)
+        const imgArea = bestImg ? bestImg.area : 0
+        const coverage = sectionArea > 0 ? imgArea / sectionArea : 0
+        if (classMatch || coverage >= 0.8) {
+          return {
+            reason: classMatch
+              ? `wrapper-class:${classMatch}`
+              : `img-coverage:${(coverage * 100).toFixed(0)}%`,
+            imgSrc: bestImg ? bestImg.src : null,
+            imgBbox: bestImg ? bestImg.bbox : null,
+            coverage,
+          }
+        }
+        return null
+      }
       const sourceDom = result.domLive
         ? Array.isArray(result.domLive)
           ? result.domLive
@@ -496,6 +621,7 @@ async function main() {
               sectionList.push({
                 sectionType: labelFromNode(grand),
                 bbox: grand.bbox,
+                imageBlock: classifyAsImageBlock(grand),
               })
             }
           }
@@ -507,6 +633,7 @@ async function main() {
         sectionList.push({
           sectionType: labelFromNode(child),
           bbox,
+          imageBlock: classifyAsImageBlock(child),
         })
       }
 
@@ -567,6 +694,7 @@ async function main() {
               sectionType: sec.sectionType,
               bbox: sec.bbox,
               path: cropPath,
+              imageBlock: sec.imageBlock || null,
             })
           } catch (err) {
             log(`section crop ${idx} ${sec.sectionType} failed: ${err?.message || err}`)
@@ -1801,7 +1929,7 @@ function extractInPage({ selector, maxDepth, maxChildren, maxText }) {
     try {
       parsed = new DOMParser().parseFromString(snapshot.html, 'text/html')
     } catch (_) {
-      return { ...snapshot, links: [], headings: [], inputs: [], forms: [], images: [] }
+      return { ...snapshot, links: [], headings: [], inputs: [], forms: [], images: [], blocks: [], paragraphs: [], inlineSvgs: [] }
     }
     const root = parsed.body.firstElementChild || parsed.body
     const norm = (s) => (s || '').replace(/\s+/g, ' ').trim()
@@ -1812,7 +1940,8 @@ function extractInPage({ selector, maxDepth, maxChildren, maxText }) {
         label: a.getAttribute('aria-label') || null,
       }))
       .filter((l) => l.href && (l.text || l.label))
-    const headings = Array.from(root.querySelectorAll('h1, h2, h3, h4, h5, h6, p.bold, .footer__block-title, [class*="heading"]'))
+    const HEADING_SELECTOR = 'h1, h2, h3, h4, h5, h6, p.bold, .footer__block-title, [class*="heading"]'
+    const headings = Array.from(root.querySelectorAll(HEADING_SELECTOR))
       .map((h) => ({ tag: h.tagName.toLowerCase(), text: norm(h.textContent) }))
       .filter((h) => h.text)
     const inputs = Array.from(root.querySelectorAll('input')).map((i) => ({
@@ -1833,8 +1962,96 @@ function extractInPage({ selector, maxDepth, maxChildren, maxText }) {
         alt: img.getAttribute('alt') || '',
         width: img.getAttribute('width') || null,
         height: img.getAttribute('height') || null,
+        classList: Array.from(img.classList || []),
+        parentClass: img.parentElement ? Array.from(img.parentElement.classList || []) : [],
       }))
       .filter((img) => img.src)
+    // §V03-5 — inline SVG capture. Composer needs the raw SVG markup to
+    // preserve ornamental decorators (Clinicians' Choice flanking flora,
+    // social icons, payment cards when those are inline rather than <img>).
+    // Skip extremely small (single-path icon < 16x16) and absurdly large
+    // svgs that are likely page-level decorative blobs.
+    const inlineSvgs = Array.from(root.querySelectorAll('svg'))
+      .map((svg, i) => {
+        const r = svg.getBoundingClientRect ? svg.getBoundingClientRect() : { width: 0, height: 0 }
+        const w = svg.getAttribute('width') || r.width || null
+        const h = svg.getAttribute('height') || r.height || null
+        const viewBox = svg.getAttribute('viewBox') || null
+        const ariaLabel = svg.getAttribute('aria-label') || null
+        const title = svg.querySelector('title')?.textContent || null
+        const classes = Array.from(svg.classList || [])
+        return {
+          idx: i,
+          outerHTML: svg.outerHTML,
+          width: w,
+          height: h,
+          viewBox,
+          ariaLabel,
+          title,
+          classes,
+          parentClass: svg.parentElement ? Array.from(svg.parentElement.classList || []) : [],
+        }
+      })
+    // §V03-5 — blocks: heading-anchored sub-sections. Walks DOM in source
+    // order and groups text content under each heading (e.g. "Need Help?"
+    // heading + its paragraphs + its mailto link). This lets the composer
+    // emit semantically grouped output where the live source intended.
+    const blocks = []
+    let currentBlock = null
+    function nodeHeadingText(el) {
+      if (!el) return null
+      if (el.matches && el.matches(HEADING_SELECTOR)) return norm(el.textContent)
+      return null
+    }
+    function walkInOrder(el) {
+      if (!el || el.nodeType !== 1) return
+      const headingText = nodeHeadingText(el)
+      if (headingText) {
+        if (currentBlock) blocks.push(currentBlock)
+        currentBlock = {
+          heading: { tag: el.tagName.toLowerCase(), text: headingText },
+          paragraphs: [],
+          links: [],
+          mailtos: [],
+        }
+        return // don't descend; siblings of the heading carry the content
+      }
+      // collect paragraphs / inline content for the current block
+      if (currentBlock) {
+        if (el.tagName === 'P') {
+          // <p> can contain inline children (<a>, <strong>, etc.) — what
+          // matters is that it has no block-level nested elements.
+          const hasBlockChild = Array.from(el.children).some((c) =>
+            /^(DIV|UL|OL|SECTION|ARTICLE|FORM|HEADER|FOOTER|NAV|FIGURE)$/.test(c.tagName),
+          )
+          const txt = norm(el.textContent)
+          // Copyright / "All rights reserved" lines are end-of-section
+          // markers — close the current block before they get attached
+          // to an unrelated heading like "Need Help?".
+          if (/^(©|copyright)/i.test(txt) || /all rights reserved/i.test(txt)) {
+            if (currentBlock) {
+              blocks.push(currentBlock)
+              currentBlock = null
+            }
+          } else if (txt && txt.length >= 8 && !hasBlockChild) {
+            currentBlock.paragraphs.push(txt)
+          }
+        }
+        if (el.tagName === 'A') {
+          const href = el.getAttribute('href') || ''
+          if (href.startsWith('mailto:')) currentBlock.mailtos.push(href.replace(/^mailto:/, ''))
+          else if (href) currentBlock.links.push({ href, text: norm(el.textContent) })
+        }
+      }
+      for (const c of el.children) walkInOrder(c)
+    }
+    walkInOrder(root)
+    if (currentBlock) blocks.push(currentBlock)
+    // §V03-5 — paragraphs: all <p> in order, for sections without
+    // heading anchors (e.g. footer brand description sitting alone).
+    const paragraphs = Array.from(root.querySelectorAll('p'))
+      .map((p) => norm(p.textContent))
+      .filter((t) => t && t.length >= 8 && t.length < 400)
     return {
       html: snapshot.html,
       bbox: snapshot.bbox,
@@ -1843,10 +2060,18 @@ function extractInPage({ selector, maxDepth, maxChildren, maxText }) {
       inputs,
       forms,
       images,
+      inlineSvgs,
+      blocks,
+      paragraphs,
     }
   }
   const hydratedHeader = extractChrome(window.__sbHydratedHeader)
   const hydratedFooter = extractChrome(window.__sbHydratedFooter)
+  // §V03-5 announcement bar — captured separately to allow the composer
+  // to emit it as part of the global chrome (clean/global/header.html
+  // composed with the bar prepended) instead of leaking into per-page
+  // body content.
+  const hydratedAnnouncementBar = window.__sbHydratedAnnouncementBar || null
 
   return {
     sectionType,
@@ -1863,6 +2088,7 @@ function extractInPage({ selector, maxDepth, maxChildren, maxText }) {
     externalIframes,
     hydratedHeader,
     hydratedFooter,
+    hydratedAnnouncementBar,
   }
 }