similarbuild 0.3.3 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "similarbuild",
-  "version": "0.3.3",
+  "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/skills/sb-build-wp/SKILL.md

@@ -37,47 +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-3 — Section-level vision composition with ZERO-FABRICATION enforcement (REPLACES §V03-2).** The previous full-page screenshot approach (§V03-2) failed because page screenshots of 24000+ pixels tall get downscaled when read, making digits/labels unreadable — the LLM then completed gaps with plausible-but-wrong content (fabricated FAQ answers, wrong prices, hallucinated product counts, "old version of the site" pulled from training data).
+   **CANONICAL VISUAL INPUT = `sectionCrops[]`.** Do NOT read `inspection.screenshot` (full-page) — it's downscaled when loaded as image and digits become unreadable. The crops are HD-readable per section. Composer uses one crop per section it composes.
 
-   v0.3.3 fixes this with **section crops in native resolution**: `inspection.sectionCrops[]` carries one image per visual band (hero, products grid, FAQ, etc.) at the viewport's native width (390px on mobile). Each crop is HD-readable for the section it represents.
+   **§V03-4 — TERNARY section classification + ZERO-FABRICATION HARD ENFORCEMENT (replaces §V03-3).** Before composing ANY section, classify it into ONE of five categories. Pick the FIRST category that matches. Each category has a distinct compose recipe. Default = placeholder is FORBIDDEN; placeholder is only the last-resort for category (E).
 
    **Workflow when composing a body page** (anything NOT `--target-section=header|footer`):
 
-   1. **For each section you compose**, find the matching entry in `inspection.sectionCrops[]` by approximate bbox.y range and `sectionType` keyword. Read the crop image via Read tool — `Read({ file_path: cropEntry.path })`.
-
-   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".
+   1. **Find the section's crop.** For each section you compose, find the matching `inspection.sectionCrops[]` entry by `bbox.y` proximity. Read the crop via `Read({ file_path: cropEntry.path })`.
+
+   2. **Classify the section** into A / B / C / D / E:
+
+      **(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.
+
+      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

@@ -453,6 +453,84 @@ async function main() {
         const slug = (cls || tag).replace(/[^a-z0-9-]/gi, '-').toLowerCase().slice(0, 32)
         return slug || 'section'
       }
+
+      // §V03-4 image-block detection. A section is an image-block when
+      // its visible content is dominated by a single <img>: either by
+      // bbox coverage (img takes ≥80% of section area) OR by a known
+      // wrapper-class pattern (Shopify Dawn / OS 2.0 themes use specific
+      // wrapper classes like `product-info__image` to delimit a region
+      // whose entire visual content is one CDN-hosted SVG/PNG/JPG asset).
+      // The composer (sb-build-wp §V03-4 rule A) treats image-block
+      // sections as "download asset + emit <img src>" — NEVER tries to
+      // reproduce the visual contents in HTML/CSS.
+      const IMAGE_BLOCK_WRAPPER_PATTERNS = [
+        /product-info__image/i,
+        /image-with-text/i,
+        /\bhero-image\b/i,
+        /\btrust-badges\b/i,
+        /\bfeatures-points\b/i,
+        /\bmothers?-day\b/i,
+        /\bsingle-image\b/i,
+        /\bbanner-image\b/i,
+        /\bguarantee-card\b/i,
+        /\bbest-fit-size-chart\b/i,
+      ]
+      function classifyAsImageBlock(node) {
+        if (!node || typeof node !== 'object') return null
+        const sectionBbox = node.bbox
+        if (!sectionBbox || !sectionBbox.h || !sectionBbox.w) return null
+        const sectionArea = sectionBbox.h * sectionBbox.w
+        if (sectionArea <= 0) return null
+        // Match by wrapper-class pattern on the node itself OR any
+        // descendant (the wrapper might be a child of the section root).
+        function findClassMatch(n) {
+          if (!n || typeof n !== 'object') return null
+          if (Array.isArray(n.classes)) {
+            for (const cls of n.classes) {
+              for (const pat of IMAGE_BLOCK_WRAPPER_PATTERNS) {
+                if (pat.test(cls)) return cls
+              }
+            }
+          }
+          if (Array.isArray(n.children)) {
+            for (const c of n.children) {
+              const m = findClassMatch(c)
+              if (m) return m
+            }
+          }
+          return null
+        }
+        const classMatch = findClassMatch(node)
+        // Find the largest <img> descendant by bbox area.
+        let bestImg = null
+        function findBiggestImg(n) {
+          if (!n || typeof n !== 'object') return
+          if (n.tag === 'img' && n.bbox && n.bbox.h > 0 && n.bbox.w > 0) {
+            const a = n.bbox.h * n.bbox.w
+            if (!bestImg || a > bestImg.area) {
+              const src = (n.attrs && (n.attrs.src || n.attrs.srcset)) || ''
+              bestImg = { area: a, bbox: n.bbox, src }
+            }
+          }
+          if (Array.isArray(n.children)) {
+            for (const c of n.children) findBiggestImg(c)
+          }
+        }
+        findBiggestImg(node)
+        const imgArea = bestImg ? bestImg.area : 0
+        const coverage = sectionArea > 0 ? imgArea / sectionArea : 0
+        if (classMatch || coverage >= 0.8) {
+          return {
+            reason: classMatch
+              ? `wrapper-class:${classMatch}`
+              : `img-coverage:${(coverage * 100).toFixed(0)}%`,
+            imgSrc: bestImg ? bestImg.src : null,
+            imgBbox: bestImg ? bestImg.bbox : null,
+            coverage,
+          }
+        }
+        return null
+      }
       const sourceDom = result.domLive
         ? Array.isArray(result.domLive)
           ? result.domLive
@@ -496,6 +574,7 @@ async function main() {
               sectionList.push({
                 sectionType: labelFromNode(grand),
                 bbox: grand.bbox,
+                imageBlock: classifyAsImageBlock(grand),
               })
             }
           }
@@ -507,6 +586,7 @@ async function main() {
         sectionList.push({
           sectionType: labelFromNode(child),
           bbox,
+          imageBlock: classifyAsImageBlock(child),
         })
       }
 
@@ -567,6 +647,7 @@ async function main() {
               sectionType: sec.sectionType,
               bbox: sec.bbox,
               path: cropPath,
+              imageBlock: sec.imageBlock || null,
             })
           } catch (err) {
             log(`section crop ${idx} ${sec.sectionType} failed: ${err?.message || err}`)