similarbuild 0.3.2 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "similarbuild",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "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

@@ -402,6 +402,8 @@ node .claude/skills/sb-inspect-live/scripts/inspect-live.mjs \
 
 **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})`.
 
+**Section crops organizados (V03-3):** após cada inspeção, copie/link os crops de `{inspection-path}/sections/*.png` para `{output_folder}/{project-slug}/screenshots/{page.slug}/` (com prefixo de página tipo `home/`, `pdp/originals/`, `pages/privacy-policy/` etc, derivado de `page.type + page.slug`). Isso dá ao usuário uma estrutura inspecionável `screenshots/<page>/<idx>-<sectionType>.png` que ele pode abrir num browser/folder pra ver O QUE o composer recebeu como input. Use `ln -sf` (symlink) ou `cp` — sem mover, porque a inspeção também precisa da pasta original pra cross-validation.
+
 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.
@@ -574,8 +576,9 @@ Anote em `pageResults[].coverage = { buildHeight, liveMainHeight, ratio, source:
 
 Pré-checks adicionais (idênticos ao `/build-page`):
 1. `--no-auto-correct` foi passado → escala primeiro diff de cada página: rotas que iriam pra Step 4j viram ⚠️ direto.
-2. `iteration >= auto_correct_max_iterations` (default 2) → idem, vira ⚠️.
-3. **Mesmo `violations[]` 2 iterações seguidas** → fixHint não pegou. Não rode 3ª. ⚠️ imediato.
+2. `iteration >= auto_correct_max_iterations` (default 2) → page goes to **❌** (NOT ⚠️) per V03-3 zero-fabrication policy. The composer had its 2 attempts and couldn't produce a faithful build; shipping the partial output as "warning" would be misleading. Mark `pageResults[].status = ❌`, message: `"compose-failed after 2 attempts — see TODOs in {output-path} for unreadable sections"`. The fragment IS still written so the user can inspect/edit it manually, but the orchestrator's contract with the user (per V03-3 hard-fail rule) is: don't claim something is ready when it's not.
+3. **Mesmo `violations[]` 2 iterações seguidas** → fixHint não pegou. Não rode 3ª. ❌ imediato.
+4. **(V03-3) `review.violations[]` includes `composition-fabrication-detected` or `composition-todo-bloat`** (composer self-flagged unreadable sections) → goes to Step 4j once. If 2nd attempt also flags, ship as ❌ — não como ⚠️.
 
 ### Step 4j — Auto-correct iteration (loop FECHADO por página)
 

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

@@ -37,34 +37,74 @@ 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-2 — Vision-based composition (MANDATORY when composing PDPs, collections, and any page with lazy-hydrated body content).** The DOM walker runs once and can miss content that depends on JavaScript hydration triggered by viewport intersection, user interaction, or framework-internal state (Shopify Dawn/OS 2.0 PDPs are the canonical case — `<x-product-form>`, `<price-list>`, `<variant-radios>`, Loox reviews widget, "you may also like", FAQ Q&A all hide their content from the static walker). The screenshot at `inspection.screenshot` captured the page AFTER `inspect-live` did step-scroll 0→12000 + lazy-hydration waits — it is the ground truth of what the user actually sees.
+   **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.
 
-   **Workflow when composing a body page** (PDP, collection, home, anything that's NOT `--target-section=header|footer`):
+   **§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).
 
-   1. **Open the screenshot** via Read tool: `Read({ file_path: <absolute path from inspection.screenshot> })`. The image is included in your context as visual content — you can SEE the page.
-   2. **Identify visible components** in the section bbox you're composing: gallery images (count and approximate aspect), price (current + compare-at if struck through), sale banners, variant selectors (size dropdowns, color swatches), tier pricing offers, CTAs (color, label text), reviews snippets, trust badges, FAQ accordions, etc.
-   3. **For each visible component, emit REAL markup** reflecting what you saw. Examples:
-      - 6-thumb gallery visible → emit `<ul class="pdp__thumbs"><li><img src="…" alt="…"></li>×6</ul>` with the thumb URLs taken from `inspection.imgUrls` filtered by Shopify-CDN patterns + product-slug match. If a thumb URL isn't in imgUrls, emit a `<!-- TODO: thumb N — visible in screenshot at (x,y), no src in inspection -->` comment and a placeholder `<img>` so the user knows.
-      - Price "$29.00" with strikethrough "$34.00" → `<span class="pdp__price">$29.00</span> <s class="pdp__compare">$34.00</s>` — read the digits LITERALLY from the screenshot, do not pull from a different DOM source unless they match.
-      - "Mother's Day Sale — Buy 2 Pairs, Get 2 FREE" banner → emit the banner with the EXACT text you read.
-      - 3 tier offers (1 Pair $29, 2 Pairs + 2 FREE $58, 3 Pairs + 5 FREE $88) → emit 3 radio cards with the literal pricing and "Best Seller"/"Best Value" badges as you see them.
-      - Variant selectors (Size XL dropdown, Color "Classic Black" dropdown) → emit `<select>` elements with option lists matching what's visible (you may not see all options if dropdown is closed — emit the ones visible + a `<!-- TODO: additional options likely below the fold -->` comment).
-      - CTA "ADD TO CART" red button → emit `<button class="pdp__cta">ADD TO CART</button>` with red background color sampled from your visual reading (or use a known brand red from `inspection.tokens.colors`).
+   **Workflow when composing a body page** (anything NOT `--target-section=header|footer`):
 
-   4. **Hybridize DOM + vision**:
-      - **Texts and visible structure** → read from screenshot (most reliable for lazy-hydrated content).
-      - **`href` for clickable links** → look in `inspection.domLive` / `inspection.hydratedHeader` / `inspection.hydratedFooter` / `inspection.imgUrls` for matching elements (by visible link text or image alt). If no match, emit `href="#"` plus a `<!-- TODO: resolve href for "…" -->` comment.
-      - **`form action`, `method`, hidden inputs** → ALWAYS from `inspection.hydratedFooter.forms` / `inspection.dom` / `inspection.domLive` (never guess these — submission will break).
-      - **`src` for images** → resolve via `assetsMap.assets[url].localPath` when URL appears in `inspection.imgUrls`. When you see an image in the screenshot but can't find its URL in imgUrls (custom-element-rendered img), emit a placeholder + TODO comment.
-      - **Computed style (fonts, colors, spacing)** → from `inspection.tokens` + `domLive[].computedStyle` (canonical for layout-derivable values like body background).
+   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 })`.
 
-   5. **No fabrication, but vision-reading is NOT fabrication.** Emitting `<span>$29.00</span>` when you can clearly SEE "$29.00" in the screenshot is reading, not inventing. The fabrication rule means: don't make up content that isn't in either the DOM or the screenshot. It does NOT mean ignore the screenshot.
+   2. **Classify the section** into A / B / C / D / E:
 
-   6. **Coverage gate.** When composing PDPs, aim for: gallery + price + variants + CTA + (optional) reviews summary + trust badges. If any of these are visible in the screenshot but you cannot emit faithful markup (e.g. complex tier pricing with sliders), emit a STRUCTURAL placeholder + clear TODO comment — never leave a section bare.
+      **(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.
 
-   Vision-based composition is the v0.3.2 answer to the v0.3.0 catch-22 (Cap A flatten sees shadow content but loses bbox; domLive has bbox but misses shadow content). The screenshot is the ground truth that bridges both.
+      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.
+
+      **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).
+
+      **(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.
+
+      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.
+
+   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).
 

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

@@ -422,6 +422,245 @@ async function main() {
 
     Object.assign(result, extracted)
 
+    // §V03-3 — Section-level crops at NATIVE resolution.
+    // The full-page screenshot can be 24k+ pixels tall on long pages;
+    // when a vision model reads it, the image is downscaled to fit and
+    // small details (prices, badges, button labels) become unreadable.
+    // Capture each classified section as its own viewport-width crop in
+    // native resolution so the composer can read details accurately.
+    log('capturing section-level crops')
+    try {
+      const cropsDir = join(OUTPUT_DIR, 'sections')
+      await mkdir(cropsDir, { recursive: true })
+
+      // Strategy: capture TOP-LEVEL vertical bands. Walk into <body>/<main>
+      // and treat each direct child with meaningful height as a section
+      // crop. classifySection's sectionType (when present) is preserved
+      // as the section label; otherwise we tag with the element's tag +
+      // first class. This is more complete than relying on classifySection
+      // alone — many real-world pages have hero/trust/pillars/guarantee/
+      // banner that classifySection doesn't recognize as a known type but
+      // are clearly distinct visual bands.
+      const sectionList = []
+      const seenBbox = new Set()
+      function bboxKey(b) {
+        return `${b?.x}|${b?.y}|${b?.w}|${b?.h}`
+      }
+      function labelFromNode(n) {
+        if (n.sectionType) return n.sectionType
+        const cls = Array.isArray(n.classes) ? n.classes[0] : null
+        const tag = n.tag || 'section'
+        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
+          : [result.domLive]
+        : result.dom
+
+      // Find the host container (body or main) — walk in one level and
+      // pick the node with the most children + largest bbox.
+      function findHost(arr) {
+        for (const node of arr) {
+          if (!node || typeof node !== 'object') continue
+          if (node.tag === 'body' || node.tag === 'main') return node
+          // Recurse one level for the case the root is e.g. <html>
+          if (Array.isArray(node.children)) {
+            const inner = findHost(node.children)
+            if (inner) return inner
+          }
+        }
+        return null
+      }
+      const host = findHost(sourceDom)
+      const directChildren = host && Array.isArray(host.children) ? host.children : sourceDom
+
+      for (const child of directChildren) {
+        if (!child || typeof child !== 'object') continue
+        const bbox = child.bbox
+        if (!bbox || typeof bbox.h !== 'number') continue
+        // Skip tiny strips (probably wrappers/spacers) and zero-height.
+        if (bbox.h < 60 || bbox.w < 200) continue
+        // Skip absurdly tall single bands (entire page wrapped in one
+        // div) — fall back to nested crops in that case.
+        if (bbox.h > 6000) {
+          if (Array.isArray(child.children)) {
+            for (const grand of child.children) {
+              if (!grand || typeof grand !== 'object' || !grand.bbox) continue
+              if (grand.bbox.h < 60 || grand.bbox.w < 200) continue
+              if (grand.bbox.h > 6000) continue
+              const key = bboxKey(grand.bbox)
+              if (seenBbox.has(key)) continue
+              seenBbox.add(key)
+              sectionList.push({
+                sectionType: labelFromNode(grand),
+                bbox: grand.bbox,
+                imageBlock: classifyAsImageBlock(grand),
+              })
+            }
+          }
+          continue
+        }
+        const key = bboxKey(bbox)
+        if (seenBbox.has(key)) continue
+        seenBbox.add(key)
+        sectionList.push({
+          sectionType: labelFromNode(child),
+          bbox,
+          imageBlock: classifyAsImageBlock(child),
+        })
+      }
+
+      // Sort by y so crops are numbered top-to-bottom — matches the
+      // user's reading order through the page.
+      sectionList.sort((a, b) => (a.bbox.y || 0) - (b.bbox.y || 0))
+
+      // Use sharp to crop the already-captured full-page screenshot.
+      // This is faster (no extra page.screenshot per section) and avoids
+      // page-level scroll/layout race conditions where clip regions outside
+      // the rendered viewport return "clipped area outside resulting image".
+      // The screenshot was captured at deviceScaleFactor=3 for iPhone profile,
+      // so pixel coords are bbox-coord * dpr; we read metadata to detect.
+      let sharp = null
+      try {
+        sharp = (await import('sharp')).default
+      } catch (_) {
+        log('sharp not available — section crops skipped (install: npm i sharp)')
+        result.sectionCrops = []
+      }
+      const sectionCrops = []
+      if (sharp) {
+        const fullMeta = await sharp(screenshotPath).metadata()
+        const dpr = Math.max(1, Math.round(fullMeta.width / VIEWPORT_W))
+        let idx = 0
+        for (const sec of sectionList) {
+          idx++
+          const slug =
+            String(idx).padStart(2, '0') +
+            '-' +
+            String(sec.sectionType).replace(/[^a-z0-9-]/gi, '-').toLowerCase()
+          const cropPath = join(cropsDir, `${slug}.png`)
+          // Clamp to image bounds — bbox may extend beyond captured area.
+          const extractW = Math.max(
+            1,
+            Math.min(Math.round((sec.bbox.w || VIEWPORT_W) * dpr), fullMeta.width),
+          )
+          const extractH = Math.max(
+            1,
+            Math.min(Math.round(sec.bbox.h * dpr), fullMeta.height - Math.round(sec.bbox.y * dpr)),
+          )
+          const extractY = Math.max(0, Math.round(sec.bbox.y * dpr))
+          if (extractY + extractH > fullMeta.height || extractH < 30 * dpr) {
+            log(`section crop ${idx} ${sec.sectionType} skipped: outside image bounds`)
+            continue
+          }
+          try {
+            await sharp(screenshotPath)
+              .extract({
+                left: 0,
+                top: extractY,
+                width: extractW,
+                height: extractH,
+              })
+              .toFile(cropPath)
+            sectionCrops.push({
+              idx,
+              sectionType: sec.sectionType,
+              bbox: sec.bbox,
+              path: cropPath,
+              imageBlock: sec.imageBlock || null,
+            })
+          } catch (err) {
+            log(`section crop ${idx} ${sec.sectionType} failed: ${err?.message || err}`)
+          }
+        }
+      }
+      result.sectionCrops = sectionCrops
+      log(`section crops: ${sectionCrops.length} captured`)
+    } catch (err) {
+      log(`section crops phase failed: ${err?.message || err}`)
+      result.sectionCrops = []
+    }
+
     // §3.2 — Trigger-and-observe header hamburger menu, if present.
     // Composer was guessing "Pattern A drawer-left" from sectionType=header
     // alone, ending up with the wrong animation in example-shop (the live