similarbuild 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "similarbuild",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "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/commands/build-site.md

@@ -67,7 +67,7 @@ O texto após `ARGUMENTS:` contém a entrada do usuário. Extraia:
 | `--no-auto-correct` | no | false | Em cada página, escala no primeiro decision-matrix que pediria loop. |
 | `--max-pages <n>` | no | (deixa o default da skill, `200`) | Repassa pra `sb-crawl-and-list` como hard cap. |
 | `--sitemap-path <path>` | no | (none) | Repassa pra `sb-crawl-and-list`. Útil pra SPAs ou sites que bloqueiam crawler. |
-| `--no-globals` | no | false | Opt-out explícito do Step 4d (globals auto-extract). Sem essa flag, header/footer compartilhados são extraídos pra `clean/global/` quando `crawl.pageCount >= 3` (default ON). Use quando o site não tem chrome compartilhado entre páginas, ou quando estiver fazendo um run de debug que precisa ver o markup completo por página. |
+| `--no-globals` | no | false | Opt-out do Step 3.5 (globals-first phase, V03-0a). Sem essa flag, header/footer compartilhados são extraídos pra `clean/global/` ANTES do loop de páginas, com gates duros de interactivity+visual. Default ON quando `crawl.pageCount >= 3` AND existe ≥1 página `type === 'home'`. Use quando o site não tem chrome compartilhado, ou em debug que precisa ver markup completo por página. |
 | `--dry-run` | no | false | Roda crawl + checkpoint + plan-summary, **não builda**. Imprime o plano (URLs, types, assets estimados) e sai. |
 
 Flag desconhecida → ignore com warning de uma linha. Não erre.
@@ -105,7 +105,7 @@ Flag desconhecida → ignore com warning de uma linha. Não erre.
    │   ├── collections/         ← um por collection
    │   ├── pages/               ← contact/about/policy/blog/other
    │   ├── sections/            ← seções genéricas
-   │   └── global/              ← header/footer compartilhados (Step 4d)
+   │   └── global/              ← header/footer compartilhados (Step 3.5, V03-0a)
    ├── assets/                  ← content-hash images, COMPARTILHADO entre todas as páginas
    ├── reports/
    │   ├── diffs/
@@ -227,7 +227,136 @@ Mostre a lista FINAL pós-filtro (mesma tabela formatada, mas com a contagem nov
 
 ### Step 3d — Dry-run check
 
-Se `--dry-run` foi passado, AGORA é o ponto de saída: depois de `confirm`, escreva `reports/plan.{ts}.md` com a lista final + estimativa por type, imprima o sumário, e pare. Não rode Step 4.
+Se `--dry-run` foi passado, AGORA é o ponto de saída: depois de `confirm`, escreva `reports/plan.{ts}.md` com a lista final + estimativa por type, imprima o sumário, e pare. Não rode Step 3.5 nem Step 4.
+
+---
+
+## Step 3.5 — Globals-first phase (V03-0, hydrated-snapshot powered)
+
+**Default ON** quando `crawl.pageCount >= 3` AND a flag `--no-globals` NÃO foi passada AND existe ao menos uma página com `type === 'home'` em `pagesConfirmed[]`. Caso contrário, skip o Step 3.5 inteiro com uma linha em `decisions.md` (`Step 3.5 skipped: <reason>`) e segue pro Step 4 com `globalsExtracted = { header: null, footer: null, status: 'skipped' }`.
+
+Header/footer são **shared chrome**: usados em TODAS as páginas. Bug em qualquer um afeta o site inteiro. Esta fase é dedicada e roda ANTES do loop de páginas pra evitar gastar tempo nas páginas individuais quando os globais estão quebrados.
+
+**Diferença vs tentativa anterior (revertida em v0.2.2)**: agora o `sb-inspect-live` emite `inspection.hydratedHeader` / `inspection.hydratedFooter` — payloads estruturados (links, headings, inputs, forms, images) capturados WHILE THE CHROME IS IN VIEW e ainda hidratado. Isso elimina o problema de lazy-light-DOM em Shopify (onde menus `<store-footer-menu>` populam `<li>` via JS pós-intersection-out). Composer compõe markup REAL — não image-slice estática.
+
+Estado do orchestrator:
+
+```
+globalsExtracted = {
+  header: null | <output-path>,    // ex: "clean/global/header.html"
+  footer: null | <output-path>,
+  status: 'extracted' | 'skipped' | 'failed',
+  failureReason: null | <string>,
+  headerBbox: null | {x,y,w,h},
+  footerBbox: null | {x,y,w,h},
+  homeInspectionPath: null | <path>,
+}
+```
+
+### Step 3.5a — Inspect home (Bash, dedicado)
+
+```bash
+node .claude/skills/sb-inspect-live/scripts/inspect-live.mjs \
+  --url "{home-page.url}" \
+  --viewport-width {default_viewport} \
+  --viewport-height 844 \
+  --output-dir "{output_folder}/{project-slug}/.sb-memory/inspect-globals-{ts}"
+```
+
+Onde `{home-page}` é a primeira entrada de `pagesConfirmed[]` com `type === 'home'`. Set `globalsExtracted.homeInspectionPath` = path resultante. Se inspect falha (`widgetBlocked`, exit non-zero), `globalsExtracted.status = 'failed'`, `failureReason = 'home-inspect-failed: <stderr>'`, segue pro Step 3.5g.
+
+### Step 3.5b — Detect hydrated chrome
+
+Carregue `inspection.json` da Step 3.5a:
+
+- **Header**: se `inspection.hydratedHeader !== null` AND `inspection.hydratedHeader.links.length >= 2`, set `globalsExtracted.headerBbox = inspection.hydratedHeader.bbox`. Caso contrário, set `globalsExtracted.header = null` (skip header compose).
+- **Footer**: se `inspection.hydratedFooter !== null` AND (`inspection.hydratedFooter.links.length >= 3` OR `inspection.hydratedFooter.forms.length >= 1`), set `globalsExtracted.footerBbox = inspection.hydratedFooter.bbox`. Caso contrário, set `globalsExtracted.footer = null`.
+
+Se AMBOS skipped, `globalsExtracted.status = 'skipped'`, `failureReason = 'no-hydrated-chrome-detected'`. Log `[build-site] Step 3.5: no hydrated header/footer in home inspection — pages keep chrome inline`. Pula direto pro Step 4 (cenário válido — não é falha).
+
+### Step 3.5c — Compose globals (Skill por target)
+
+Para cada um dos detectados (`header` e/ou `footer`), invoque o composer:
+
+```
+Skill(
+  skill="sb-build-wp",
+  args="inspection={globals-inspection-path} assets-map={assets-map-path} output-path=clean/global/{header|footer}.html preset=wp-elementor target-section={header|footer}"
+)
+```
+
+O composer consome `inspection.hydratedHeader` / `inspection.hydratedFooter` (per SKILL.md §V03-0a) — markup real com links, forms, imgs.
+
+(`sb-build-shopify` quando `target === shopify`, mesmo padrão.)
+
+Set `globalsExtracted.header` e/ou `.footer` = output paths. Se composer falha, `globalsExtracted.status = 'failed'`, `failureReason = 'compose-failed: <which> <stderr>'`, segue pro Step 3.5g.
+
+### Step 3.5d — Test interactivity (Bash, HARD blocker)
+
+Diferente do Step 4f-bis (diagnóstico em páginas individuais), aqui o gate é DURO. Para cada um:
+
+```bash
+node .claude/skills/sb-test-interactivity/scripts/test-interactivity.mjs \
+  --file "clean/global/{header|footer}.html" \
+  --preset "{preset}" \
+  --output-dir "{output_folder}/{project-slug}/reports/validations/global-{ts}"
+```
+
+Se `passed === false`, `globalsExtracted.status = 'failed'`, `failureReason = 'interactivity-failed: <which>'`, segue pro Step 3.5g.
+
+### Step 3.5e — Compare visual focado em crops
+
+Pré-condição: cada fragment já foi composto. Renderize cada um e compare contra o crop correspondente da live screenshot.
+
+**3.5e.i — Render do fragment**:
+
+```bash
+node .claude/skills/sb-validate-static-render/scripts/validate-static-render.mjs \
+  --file "clean/global/{header|footer}.{html|liquid}" \
+  --preset "{preset}" \
+  --output-dir "{output_folder}/{project-slug}/reports/validations/global-{ts}/{header|footer}/"
+```
+
+**3.5e.ii — Bbox no live**: use `globalsExtracted.headerBbox` (ou `footerBbox`). Se `w === 0 || h === 0`, log warning e omita `--crop-live-bbox` (compare-visual cai pra comparação full-screen).
+
+**3.5e.iii — Compare**:
+
+```bash
+node .claude/skills/sb-compare-visual/scripts/compare-visual.mjs \
+  --live-screenshot "{globals-inspection-screenshot}" \
+  --build-screenshot "{globals-render-screenshot}" \
+  --output-dir "{output_folder}/{project-slug}/reports/diffs/global-{ts}/{header|footer}/" \
+  --tokens-live "{globals-inspection-path}" \
+  --tokens-build "{globals-render-json-path}" \
+  --threshold {diff_threshold_percent} \
+  [--crop-live-bbox "{x},{y},{w},{h}"] \
+  [--crop-build-bbox "0,0,{width},{totalHeight}"]
+```
+
+Se `passed === false`, `globalsExtracted.status = 'failed'`, `failureReason = 'visual-diff: <which> <diffPercent>%'`, segue pro Step 3.5g.
+
+### Step 3.5f — Sucesso
+
+`globalsExtracted.status = 'extracted'`. Log `[build-site] Step 3.5 ✅ globals extracted: header={path}, footer={path}`. Prossegue pro Step 4.
+
+### Step 3.5g — Gate duro (early-exit em falha)
+
+Se `globalsExtracted.status === 'failed'`:
+
+1. Escreva `reports/index.html` mínimo com o motivo + links pros artefatos diagnósticos.
+2. Append em `decisions.md`: `{ts} | /build-site {root-URL} | Step 3.5 BLOCKED: {failureReason} | pages NOT processed`.
+3. Console:
+
+   ```
+   ❌ /build-site {root-URL}
+
+     Step 3.5 (globals pass) bloqueou o batch.
+     Motivo: {failureReason}
+     Artefatos: {output_folder}/{project-slug}/reports/index.html
+
+     Páginas individuais NÃO foram processadas — fix os globals e re-rode.
+   ```
+4. Pare.
 
 ---
 
@@ -271,6 +400,8 @@ node .claude/skills/sb-inspect-live/scripts/inspect-live.mjs \
   --output-dir "{output_folder}/{project-slug}/.sb-memory/inspect-{slug}-{ts}"
 ```
 
+**Re-uso da inspection da home (V03-0a):** se `page.type === 'home'` AND `globalsExtracted.homeInspectionPath !== null`, SKIP esta inspeção e re-use `globalsExtracted.homeInspectionPath` como o `{inspection-path}` deste step. Step 3.5a já inspecionou a home — re-rodar custaria ~5-8s e produziria conteúdo idêntico. Logue `[build-site] Step 4b: re-using home inspection from Step 3.5 ({path})`.
+
 Capture `inspection`. Branches específicas do batch:
 
 - `inspection.widgetBlocked === true` → marque a página como `❌` em `pageResults[]`, anote o motivo, e **continue para a próxima página** (não pare o batch). Exceção: se essa for a PRIMEIRA página E for a `home`, pare e escale — provavelmente o site inteiro está atrás de bot-wall.
@@ -291,50 +422,29 @@ node .claude/skills/sb-extract-assets/scripts/extract-assets.mjs \
 
 `assetsMap.failed[]` non-empty → forwarde pro builder, **não** pare a página.
 
-### Step 4d — Extract global sections (header/footer compartilhados)
+### Step 4d — Strip globals from per-page inspection (V03-0a, post-Step 3.5)
 
-**Default ON** quando `crawl.pageCount >= 3` AND a flag `--no-globals` NÃO foi passada. Caso contrário, skip este Step inteiro com uma linha em `decisions.md` (`Step 4d skipped: pageCount<3` OU `Step 4d skipped: --no-globals opt-out`).
+A detecção e composição de header/footer **agora roda no Step 3.5** (Globals-first phase, antes do loop). Aqui o trabalho é apenas garantir que páginas individuais NÃO incluam header/footer no markup gerado — o destino renderiza os globais UMA vez via `clean/global/{header,footer}.{html|liquid}`.
 
-Estado mantido pelo orchestrator durante o batch:
+**Skip este Step** se `globalsExtracted.status !== 'extracted'` (Step 3.5 foi `skipped` ou retornou sem chrome detectado). Páginas mantêm chrome inline — comportamento pré-v0.3.0 para sites sem chrome global.
 
-```
-globalsExtracted = {
-  header: null | <output-path>,   // ex: "clean/global/header.html"
-  footer: null | <output-path>,
-}
-```
-
-**Detector estrutural** (sem hash, sem regex sobre HTML cru):
-
-- **Header** = primeiro elemento da `inspection.dom` (descida em DFS) cujo `tag === 'header'` E que tenha algum descendant cujo `tag === 'nav'`. Se ausente: **skip globals (não extrai nem strippa) + log warning** em `decisions.md`: `[build-site] WARN: Step 4d header detector missed — no <header> semântico com <nav>; globals not extracted, pages keep chrome inline`. Continue pipeline normalmente. **NÃO pergunte ao humano** — non-negotiable #5 (`single human checkpoint = page list confirmation`) proíbe queries mid-batch. Decisão de fix manual fica pra próximo run com `--no-globals` ou refresh do crawl.
-
-- **Footer** = último elemento que é **descendant direto-de-body-ou-main** (i.e., `parent.tag === 'body'` OU `parent.tag === 'main'`) cujo `tag === 'footer'` OU cujo atributo `role === 'contentinfo'`. **NÃO** o último em DFS pós-ordem — isso pegava blog-post `<footer>` ou article `<footer>` em vez do site footer (bug example-shop-class em sites de conteúdo). Se ausente: skip + warn (mesmo padrão do header acima).
-
-**Trigger window:** Step 4d roda apenas quando `globalsExtracted.header === null` (e separadamente para footer). Ou seja, só na primeira inspection que casar o detector. Inspeções subsequentes não re-processam — o asset já está em disco e é referenciado.
-
-**Extração:**
-1. Localize header e/ou footer no `inspection.dom` (em memória).
-2. Serialize cada um pro fragment HTML/Liquid passando pelo composer (`sb-build-wp` ou `sb-build-shopify`) com hint `--target-section=header|footer` (composer trata como input de seção, não página inteira). Output: `clean/global/{header,footer}.{html|liquid}`.
-3. Set `globalsExtracted.header` (e/ou `.footer`) = output path.
-
-**Stripper (mandatório quando globals extracted):** ANTES de invocar o composer pra páginas individuais (Step 4e):
+**Stripper (mandatório quando `globalsExtracted.status === 'extracted'`):** ANTES de invocar o composer pra esta página (Step 4e):
 
 1. Clone a `inspection` em memória.
-2. Em `inspection.dom`, **remova** as subtrees do `<header>` semântico (se `globalsExtracted.header !== null`) e do `<footer>`/`[role=contentinfo]` (se `globalsExtracted.footer !== null`).
-3. Passe a inspection editada ao composer. Composer não vê header/footer e não pode fabricá-los.
-4. Após o composer retornar, **prepende** ao output uma linha de comentário:
+2. Em `inspection.dom`, **remova** as subtrees do `<header>` semântico (se `globalsExtracted.header !== null`) e do `<footer>` / `[role=contentinfo]` (se `globalsExtracted.footer !== null`). Use heurística "parent imediato": o tag `<footer>` direto-de-body-ou-main qualifica; `<article><footer>` aninhado em layouts blog NÃO qualifica.
+3. Também limpe `inspection.hydratedHeader` e `inspection.hydratedFooter` (set null) na cópia editada — assim o composer não tenta re-renderizar o chrome global na página individual.
+4. Passe a inspection editada ao composer.
+5. Após o composer retornar, **prepende** ao output uma linha de comentário:
    - HTML: `<!-- sb-build-site: header in clean/global/header.html -->\n` (se header extracted)
    - HTML: `<!-- sb-build-site: footer in clean/global/footer.html -->` (se footer extracted, no fim)
    - Liquid: idem com `{% comment %} ... {% endcomment %}`
-5. Grava em `clean/{home,pdp,...}/{slug}.html` o output já strippado-e-comentado.
+6. Grava em `clean/{home,pdp,...}/{slug}.html` o output já strippado-e-comentado.
 
-**Stripper validation:** após gravar o file, faça um grep rápido:
+**Stripper validation:** após gravar, faça grep:
 ```
 grep -nE "<header[ >]|<footer[ >]" clean/{home,pdp,...}/{slug}.{html,liquid}
 ```
-Padrão sem `^` anchor pra pegar pretty-printed (indented `  <header>`). Glob `{html,liquid}` cobre ambos os targets (WP + Shopify). Se retornar match, é defeito — composer ignorou a inspection editada e re-fabricou, ou stripper passou tag misformada. Log `[build-site] WARN: stripper miss in {slug}.{ext}` em `decisions.md`. Não blocking — orchestrator continua.
-
-**Por que detector estrutural e não hash:** hash exige inspection emitir hashes comparáveis. Detector estrutural usa só tags semânticas que `sb-inspect-live` já captura na DOM tree. Funciona com qualquer inspection que tenha um DOM serializado, sem mudança upstream. Cobre o caso comum (sites WordPress/Shopify usam `<header>`/`<footer>` semântico). Para sites com chrome em `<div class="site-header">` sem semântica, o Ask First gate força decisão consciente em vez de heurística silenciosa.
+Match → log `[build-site] WARN: stripper miss in {slug}.{ext}` em `decisions.md`. Não-blocking — orchestrator continua, mas vira entry em "Stripper misses" no report final.
 
 ### Step 4e — Build (Skill)
 
@@ -492,11 +602,13 @@ Depois que TODAS as páginas confirmadas foram processadas (`pageResults[].lengt
 
 1. **Escreva `{output_folder}/{project-slug}/reports/index.html`** com:
    - Header com root URL, target, project-slug, timestamp do run, totals (`X✅ / Y⚠️ / Z❌`).
+   - **Section "Globals extraction" (V03-0a)** logo abaixo do header, ANTES da tabela: badge ✅/❌/⏭️ (extracted/failed/skipped) + `globalsExtracted.status`, `globalsExtracted.failureReason` quando aplicável, links pra `clean/global/header.html` e `clean/global/footer.html` quando extracted, link pro `interactivity-report.json` da fase global, link pro diff map da fase global. Se `status === 'failed'`, esta seção é a única coisa renderizada antes do "batch BLOCKED" notice — não há tabela de páginas (Step 3.5g já abortou).
    - Tabela com uma linha por página: status badge (com sufixos `+!interactive` quando aplicável), type, URL → output path link, diff %, **coverage %**, iterations, screenshot side-by-side (live + build, thumbs com link pro full), link pro diff map, violations resumo, link pro `interactivity-report.json` quando `interactivityWarnings.length > 0`.
    - Section "Auto-correct details" listando páginas com iteration > 0 e o que mudou.
    - Section "Escalations" com páginas ⚠️/❌ — top diffs visuais e candidate fixes inline.
    - Section "Interactivity warnings" listando páginas com `interactivityWarnings.length > 0`, agrupadas por type de teste reprovado (aria-controls / details-summary / dialog) e mostrando o trigger/target + check name por failure.
    - Section "Coverage warnings" listando páginas com `coverage.ratio < 0.85`, ordenadas por ratio asc — primeiro caso é o mais crítico.
+   - Section "Stripper misses" (V03-0a) — listar entries de `decisions.md` matchando `WARN: stripper miss in <slug>` quando `globalsExtracted.status === 'extracted'`, com link pro arquivo offending pra revisão manual.
    - Footer com: link pra `pages-confirmed.json`, link pro `crawl/pages-list.json` (raw discovery), config snapshot.
 
 2. **Persistência cumulativa.** Se o `report.html` já existir (rerun), preserve runs anteriores em uma section "Previous runs" (hierárquica por timestamp). O run mais recente fica no topo. NÃO sobrescreva tudo.

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

@@ -37,7 +37,17 @@ 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`, `pseudoElements`, `imgUrls`) 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`, `pseudoElements`, `imgUrls`, **`hydratedHeader`**, **`hydratedFooter`**) and `assets-map.json` (the URL → localPath / inline-SVG dictionary). If `fixHints` is given, also read `previousHtmlPath`.
+
+   **§V03-0a — `hydratedHeader` / `hydratedFooter` payload.** When `inspect-live` captures the page chrome WHILE THE BOTTOM IS IN VIEW, it snapshots the hydrated HTML before Shopify themes tear menus down on intersection-out. The payload is the canonical source of truth for header/footer composition — prefer it over `dom[]` subtrees, which may be empty `<ul>` shells if the live walker ran after tear-down. Each one has:
+   - `html`: outerHTML of the chrome subtree (string).
+   - `bbox`: `{x,y,w,h}` of the chrome at snapshot time (may reflect bottom-scroll position; the walker emits its own subtree bbox on `dom[]` if you need the at-top layout).
+   - `links[]`: every `<a href>` inside, as `{href, text, label}`. Use these for menu items, policy links, social, etc.
+   - `headings[]`: every `<h1>`...`<h6>` and `<p class="bold">`, as `{tag, text}`. Use these for column titles ("More Information", "Collections", "Need Help?").
+   - `inputs[]` / `forms[]`: full input + form metadata for newsletter signup or contact widgets — preserve `action`/`method` verbatim so the form actually submits.
+   - `images[]`: every `<img>` with src + alt + dimensions.
+
+   When composing a `--target-section=header` or `--target-section=footer` fragment AND the matching `hydratedHeader`/`hydratedFooter` is non-null, BUILD FROM THE STRUCTURED PAYLOAD, not from `dom[]`. This is mandatory whenever the payload is present — it eliminates the entire class of "shadow-dom-opaque" / lazy-light-DOM fabrication risks that previously forced image-slice fallback.
 
 1.5. **Pre-dispatch checklist.** Before composing, run:
 
@@ -84,6 +94,34 @@ A single `.html` file written to `outputPath`. The file is a fragment — no `<h
 | Pattern doesn't match any section in `inspection.dom` | Section type detected but markup is ambiguous | Pick the closest pattern from A-H, document the choice in a comment, and surface to the orchestrator. |
 | Prettier missing                                | Optional dep not installed                    | Non-fatal — `write` reports `formatted: false, formatterSkippedReason: "prettier-not-installed"`. Output is still written. |
 
+## §V03-0a — Header / Footer composition from hydrated snapshot
+
+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):
+
+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.
+
+**Header recipe** (when `hydratedHeader` present):
+
+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.
+
+**Output contract for header/footer:**
+- Markup includes a top comment `<!-- sb-build-wp: composed from hydrated snapshot (V03-0a) -->`.
+- `fabricationRisks` array in the metadata is empty for these sections (hydrated data IS the truth — no fabrication concern).
+- If `hydratedHeader`/`hydratedFooter` is NULL or empty, fall back to the prior A-H pattern lookup OR — as last resort — image-slice from screenshot bbox.
+
 ## Conventions
 
 - Bare paths (e.g. `scripts/build-wp.mjs`) resolve from the skill root.

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

@@ -29,7 +29,7 @@ Optional:
   --wait-strategy <name>  lazy-load (default) | auto | kaching-bundles | judge-me
   --max-depth <n>         DOM walk max depth (default 8).
   --max-children <n>      Max children kept per node (default 60).
-  --max-text <n>          Max chars of direct text per node (default 240).
+  --max-text <n>          Max chars of direct text per node (default 0 = no truncation; pass a positive integer to cap).
   --timeout <ms>          Per-step timeout (default 30000).
   --help                  Show this message.
 
@@ -55,7 +55,7 @@ const { values } = parseArgs({
     'output-dir': { type: 'string' },
     'max-depth': { type: 'string', default: '8' },
     'max-children': { type: 'string', default: '60' },
-    'max-text': { type: 'string', default: '240' },
+    'max-text': { type: 'string', default: '0' },
     timeout: { type: 'string', default: '30000' },
     help: { type: 'boolean', default: false },
   },
@@ -196,9 +196,107 @@ async function main() {
         window.scrollTo(0, y)
         await sleep(150)
       }
-      window.scrollTo(0, 0)
     })
 
+    // §V03-0a — lazy-hydration wait WHILE SCROLLED TO BOTTOM. Many
+    // Shopify themes populate footer menus (Contact, Privacy Policy,
+    // Collections links) via <store-footer-menu>-style custom elements
+    // only AFTER the host intersects the viewport. Wait here, with the
+    // footer in view, for any <footer> <ul> to gain children or for
+    // <footer> <a href> count to reach >= 3.
+    log('waiting for lazy-hydrated footer content (max 5s)')
+    try {
+      await page.waitForFunction(
+        () => {
+          const lists = document.querySelectorAll('footer ul, [class*="footer"] ul')
+          for (const ul of lists) {
+            if (ul.children.length > 0) return true
+          }
+          const links = document.querySelectorAll('footer a[href], [class*="footer"] a[href]')
+          return links.length >= 3
+        },
+        { timeout: 5000 },
+      )
+      log('footer content hydrated')
+    } catch (_) {
+      log('footer hydration timeout — proceeding')
+    }
+
+    // §V03-0a — capture hydrated chrome HTML WHILE STILL IN VIEW.
+    // Shopify themes that populate footer menus on viewport intersection
+    // sometimes tear the content down when the host leaves the viewport.
+    // The walker can't see torn-down menus. Snapshot the relevant
+    // subtrees here, before we scroll back to the top for layout reads,
+    // and stash them on `window` for extractInPage to read during walk.
+    log('snapshotting hydrated header/footer HTML for downstream use')
+    await page.evaluate(() => {
+      function pickFooter() {
+        const candidates = document.querySelectorAll(
+          'footer, [class*="footer"][class*="section"], [role="contentinfo"]',
+        )
+        let best = null
+        for (const el of candidates) {
+          const r = el.getBoundingClientRect()
+          if (r.height < 50) continue
+          const links = el.querySelectorAll('a[href]').length
+          const inputs = el.querySelectorAll('input,form').length
+          const score = links + inputs * 2 + r.height / 100
+          if (!best || score > best.score) best = { el, score }
+        }
+        return best?.el || null
+      }
+      function pickHeader() {
+        const candidates = document.querySelectorAll(
+          'header, [class*="header"][class*="section"], [role="banner"]',
+        )
+        let best = null
+        for (const el of candidates) {
+          const r = el.getBoundingClientRect()
+          if (r.height < 30) continue
+          const links = el.querySelectorAll('a[href]').length
+          const score = links + r.height / 100
+          if (!best || score > best.score) best = { el, score }
+        }
+        return best?.el || null
+      }
+      const footer = pickFooter()
+      const header = pickHeader()
+      window.__sbHydratedFooter = footer
+        ? {
+            html: footer.outerHTML,
+            bbox: (() => {
+              const r = footer.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
+      window.__sbHydratedHeader = header
+        ? {
+            html: header.outerHTML,
+            bbox: (() => {
+              const r = header.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
+    // viewport-distant nodes returns {w:0,h:0} bboxes — walker can't
+    // read layout from the bottom. 1.2s settle for any re-hydration.
+    await page.evaluate(() => window.scrollTo(0, 0))
+    await page.waitForTimeout(1200)
+
     // Force-eager: any <img loading="lazy"> that didn't intersect during scroll
     // gets rewritten to eager and re-fetched. <picture> sources too.
     log('forcing eager image fetch')
@@ -960,6 +1058,12 @@ function extractInPage({ selector, maxDepth, maxChildren, maxText }) {
   // iframes (Klaviyo embeds, recaptcha) are recorded as opaque rectangles.
   let shadowDOMTraversed = false
   let shadowRootCount = 0
+  // §V03-C — counts hosts whose shadow tree was successfully re-serialized
+  // via getHTML+parseHTMLUnsafe and re-walked into a flattened light-DOM
+  // representation. 0 means the post-render shadow-flatten phase was either
+  // unavailable, skipped, or hit zero open roots.
+  let shadowSerializedHostCount = 0
+  const warnings = []
   const externalIframes = []
   function classifyIframePurpose(src) {
     if (!src) return null
@@ -1091,7 +1195,10 @@ function extractInPage({ selector, maxDepth, maxChildren, maxText }) {
       if (n.nodeType === 3) t += n.nodeValue
     }
     t = t.replace(/\s+/g, ' ').trim()
-    if (t.length > maxText) t = `${t.slice(0, maxText)}…`
+    // §V03-B — maxText === 0 means "no truncation" (default since v0.3.0).
+    // Pre-v0.3.0 default was 240, which silently clipped policy paragraphs
+    // (privacy/terms) at ~25-36% coverage. The cap is now opt-in via flag.
+    if (maxText > 0 && t.length > maxText) t = `${t.slice(0, maxText)}…`
     return t
   }
 
@@ -1406,16 +1513,198 @@ function extractInPage({ selector, maxDepth, maxChildren, maxText }) {
   const dom = [walk(root, 0)].filter(Boolean)
   const { sectionType, sectionBoundingBox } = findSectionAndBox(root, !!selector)
 
+  // §V03-C — Shadow DOM serialization via getHTML + parseHTMLUnsafe.
+  // walk() above only sees light DOM and `.shadowRoot.children` direct.
+  // Custom elements whose shadow tree is populated by JS (Shopify
+  // <x-product-form>, <price-list>, <variant-radios>, <store-footer-menu>)
+  // expose content that the children-only walker can technically read,
+  // but `<slot>`-projected content and content composed from declarative
+  // shadow DOM gets fragmented. getHTML({ serializableShadowRoots: true })
+  // emits a single HTML string with `<template shadowrootmode="open">`
+  // declarations inline; parseHTMLUnsafe re-attaches those as live shadow
+  // roots in a parsed document, which the same walk() can then flatten
+  // uniformly. Layout (bbox/computedStyle) on the parsed doc is detached
+  // and returns UA defaults — that's an acknowledged trade-off; the
+  // structural content (tags, classes, attrs, text, src) is what makes
+  // PDP gallery/price/variants visible to the composer downstream.
+  const originalShadowRootCount = shadowRootCount
+  const originalShadowDOMTraversed = shadowDOMTraversed
+  // §V03-C — preserve a snapshot of the live-walker dom[] before any
+  // potential substitution. If the re-walk replaces dom[] with the
+  // shadow-flattened tree (which carries detached parsedDoc bboxes
+  // === {0,0,0,0}), downstream consumers that need real layout (e.g.
+  // /build-site Step 3.5e --crop-live-bbox for header/footer compare)
+  // can fall back to domLive. When substitution doesn't fire, domLive
+  // is left null and consumers use dom[] as-is.
+  let domLive = null
+  try {
+    if (typeof document.documentElement.getHTML === 'function' &&
+        typeof Document.parseHTMLUnsafe === 'function') {
+      const hostsSeen = new Set()
+      const hostsCollected = []
+      function collectHostsFrom(el) {
+        if (!el) return
+        if (el.shadowRoot && !hostsSeen.has(el)) {
+          hostsSeen.add(el)
+          hostsCollected.push(el)
+          for (const child of el.shadowRoot.children) collectHostsFrom(child)
+        }
+        for (const child of el.children) collectHostsFrom(child)
+      }
+      collectHostsFrom(document.documentElement)
+
+      if (hostsCollected.length > 0) {
+        const html = document.documentElement.getHTML({
+          serializableShadowRoots: true,
+          shadowRoots: hostsCollected.map((h) => h.shadowRoot),
+        })
+        const parsedDoc = Document.parseHTMLUnsafe(html)
+        const parsedRoot = selector
+          ? parsedDoc.querySelector(selector)
+          : parsedDoc.body
+        if (parsedRoot) {
+          const flattened = walk(parsedRoot, 0)
+          // §V03-C safety guard: only substitute the live dom[] if the
+          // re-walk did not lose value on EITHER axis (nodes or aggregate
+          // text chars). parseHTMLUnsafe returns a detached doc;
+          // getComputedStyle/getBoundingClientRect degrade to UA defaults
+          // (zero bbox, empty computed). On pages where shadow flattening
+          // adds value (PDPs Shopify with populated custom elements) the
+          // gain is large; on pages without that workload (policies,
+          // plain HTML), the re-walk can lose content because hydrated
+          // shadow content visible to the live walker doesn't reproduce
+          // on the detached tree. When that happens, keep the live
+          // walker result and surface a warning.
+          function measureTree(arr) {
+            let nodes = 0
+            let textChars = 0
+            const stack = Array.isArray(arr) ? [...arr] : [arr]
+            while (stack.length) {
+              const node = stack.pop()
+              if (!node || typeof node !== 'object') continue
+              nodes++
+              if (typeof node.text === 'string') textChars += node.text.length
+              if (Array.isArray(node.children)) {
+                for (const c of node.children) stack.push(c)
+              }
+            }
+            return { nodes, textChars }
+          }
+          if (flattened) {
+            const orig = measureTree(dom)
+            const flat = measureTree([flattened])
+            if (flat.nodes >= orig.nodes && flat.textChars >= orig.textChars) {
+              // Snapshot the live walker result BEFORE substitution so
+              // downstream consumers that depend on real layout (bbox
+              // values are zero on the parsed detached doc) can fall
+              // back when needed — see §V03-C domLive comment above.
+              domLive = dom.length === 1 ? dom[0] : [...dom]
+              dom.length = 0
+              dom.push(flattened)
+              shadowSerializedHostCount = hostsCollected.length
+            } else {
+              warnings.push({
+                code: 'shadow-flatten-skipped-lossy',
+                message: `re-walk lossy: nodes ${flat.nodes} vs ${orig.nodes}, textChars ${flat.textChars} vs ${orig.textChars}; keeping live walker result`,
+              })
+            }
+          }
+          // The re-walk of the parsed (detached) doc re-discovers shadow
+          // roots that parseHTMLUnsafe re-attached, so it would
+          // double-count if we let those increments leak. Restore the
+          // canonical live counts here.
+          shadowRootCount = originalShadowRootCount
+          shadowDOMTraversed = originalShadowDOMTraversed
+        }
+      }
+    } else {
+      warnings.push({
+        code: 'shadow-serialize-unavailable',
+        message:
+          'getHTML or Document.parseHTMLUnsafe not available; shadow DOM falls back to .shadowRoot.children walk (v0.2.x behavior)',
+      })
+    }
+  } catch (err) {
+    shadowRootCount = originalShadowRootCount
+    shadowDOMTraversed = originalShadowDOMTraversed
+    warnings.push({
+      code: 'shadow-serialize-failed',
+      message: String(err && err.message ? err.message : err),
+    })
+  }
+
+  // §V03-0a — extract structured content from the hydrated-chrome
+  // HTML snapshots taken before scroll-back. Shopify themes that
+  // populate menus on viewport intersection may have torn those down
+  // by the time the walker runs. The snapshots preserve the truth.
+  function extractChrome(snapshot) {
+    if (!snapshot || !snapshot.html) return null
+    let parsed
+    try {
+      parsed = new DOMParser().parseFromString(snapshot.html, 'text/html')
+    } catch (_) {
+      return { ...snapshot, links: [], headings: [], inputs: [], forms: [], images: [] }
+    }
+    const root = parsed.body.firstElementChild || parsed.body
+    const norm = (s) => (s || '').replace(/\s+/g, ' ').trim()
+    const links = Array.from(root.querySelectorAll('a[href]'))
+      .map((a) => ({
+        href: a.getAttribute('href') || '',
+        text: norm(a.textContent),
+        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"]'))
+      .map((h) => ({ tag: h.tagName.toLowerCase(), text: norm(h.textContent) }))
+      .filter((h) => h.text)
+    const inputs = Array.from(root.querySelectorAll('input')).map((i) => ({
+      type: i.getAttribute('type') || 'text',
+      name: i.getAttribute('name') || null,
+      placeholder: i.getAttribute('placeholder') || null,
+      required: i.hasAttribute('required'),
+      ariaLabel: i.getAttribute('aria-label') || null,
+    }))
+    const forms = Array.from(root.querySelectorAll('form')).map((f) => ({
+      action: f.getAttribute('action') || null,
+      method: f.getAttribute('method') || 'get',
+      id: f.getAttribute('id') || null,
+    }))
+    const images = Array.from(root.querySelectorAll('img'))
+      .map((img) => ({
+        src: img.getAttribute('src') || '',
+        alt: img.getAttribute('alt') || '',
+        width: img.getAttribute('width') || null,
+        height: img.getAttribute('height') || null,
+      }))
+      .filter((img) => img.src)
+    return {
+      html: snapshot.html,
+      bbox: snapshot.bbox,
+      links,
+      headings,
+      inputs,
+      forms,
+      images,
+    }
+  }
+  const hydratedHeader = extractChrome(window.__sbHydratedHeader)
+  const hydratedFooter = extractChrome(window.__sbHydratedFooter)
+
   return {
     sectionType,
     sectionBoundingBox,
     tokens,
     dom,
+    domLive,
     pseudoElements,
     imgUrls,
     shadowDOMTraversed,
     shadowRootCount,
+    shadowSerializedHostCount,
+    warnings,
     externalIframes,
+    hydratedHeader,
+    hydratedFooter,
   }
 }
 

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

@@ -37,6 +37,24 @@ test('--help exits 0 and prints usage', () => {
   assert.match(r.stdout, /--wait-strategy/)
 })
 
+// §V03-B — V0.3.0 changed --max-text default from 240 to 0 (no truncation).
+// This regression-protects the policy-page coverage fix.
+test('--help documents --max-text default 0 (no truncation)', () => {
+  const r = spawnSync('node', [SCRIPT, '--help'], { encoding: 'utf8' })
+  assert.equal(r.status, 0, `exit code was ${r.status}`)
+  assert.match(r.stdout, /--max-text/, '--max-text flag must appear in help')
+  // Scope the "default 0" assertion to the --max-text line specifically.
+  // The previous /default\s+0/ would match against any other flag whose
+  // description happens to contain "default 0" (e.g. a future flag whose
+  // default is "0ms" or similar).
+  assert.match(
+    r.stdout,
+    /--max-text[^\n]*default\s+0/,
+    '--max-text line must document default 0',
+  )
+  assert.match(r.stdout, /no truncation/i, 'help must explain semantics')
+})
+
 test('missing --url exits 2', () => {
   const r = spawnSync('node', [SCRIPT, '--output-dir', '/tmp/sb-test'], { encoding: 'utf8' })
   assert.equal(r.status, 2, `exit code was ${r.status}`)