similarbuild 0.3.2 → 0.3.3

package/package.json

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

@@ -39,32 +39,45 @@ A single `.html` file written to `outputPath`. The file is a fragment — no `<h
 
 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`.
 
-   **§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.
+   **§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).
 
-   **Workflow when composing a body page** (PDP, collection, home, anything that's NOT `--target-section=header|footer`):
+   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.
 
-   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. **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 })`.
 
-   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. **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.
 
-   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.
+   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.
 
-   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.
+   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.
+
+   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.
+
+   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".
+
+   This contract enforces what the user explicitly asked for: "não pode me entregar algo diferente e se nao 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-inspect-live/scripts/inspect-live.mjs

@@ -422,6 +422,164 @@ 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'
+      }
+      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,
+              })
+            }
+          }
+          continue
+        }
+        const key = bboxKey(bbox)
+        if (seenBbox.has(key)) continue
+        seenBbox.add(key)
+        sectionList.push({
+          sectionType: labelFromNode(child),
+          bbox,
+        })
+      }
+
+      // 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,
+            })
+          } 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