similarbuild 0.3.1 → 0.3.3

package/package.json

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

@@ -37,7 +37,47 @@ 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 `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 `screenshot` path) and `assets-map.json` (the URL → localPath / inline-SVG dictionary). If `fixHints` is given, also read `previousHtmlPath`.
+
+   **§V03-3 — Section-level vision composition with ZERO-FABRICATION enforcement (REPLACES §V03-2).** The previous full-page screenshot approach (§V03-2) failed because page screenshots of 24000+ pixels tall get downscaled when read, making digits/labels unreadable — the LLM then completed gaps with plausible-but-wrong content (fabricated FAQ answers, wrong prices, hallucinated product counts, "old version of the site" pulled from training data).
+
+   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.
+
+   **Workflow when composing a body page** (anything NOT `--target-section=header|footer`):
+
+   1. **For each section you compose**, find the matching entry in `inspection.sectionCrops[]` by approximate bbox.y range and `sectionType` keyword. Read the crop image via Read tool — `Read({ file_path: cropEntry.path })`.
+
+   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.
+
+   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.
+
+   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