similarbuild 0.1.0

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

@@ -0,0 +1,693 @@
+#!/usr/bin/env node
+// inspect-live.mjs — Capture a live page's DOM, computed tokens, screenshot,
+// pseudo-elements, and image URLs for SimilarBuild visual cloning.
+//
+// Mobile-first by default (390x844). Stealth chromium with realistic iPhone UA.
+// Triggers lazy-load via step-scroll + force-eager rewrite of <img loading="lazy">.
+// Outputs a single JSON object to stdout AND writes inspection.json + screenshot.png
+// into --output-dir. Logs progress to stderr.
+
+import { parseArgs } from 'node:util'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { statSync } from 'node:fs'
+
+// playwright-extra + puppeteer-extra-plugin-stealth are imported lazily inside
+// main() so --help and arg validation work without the deps installed.
+
+const HELP = `
+inspect-live.mjs — Inspect a live URL for SimilarBuild visual cloning.
+
+Required:
+  --url <url>             Absolute URL to inspect.
+  --output-dir <dir>      Directory for screenshot.png + inspection.json.
+
+Optional:
+  --viewport-width <px>   Default 390 (mobile-first).
+  --viewport-height <px>  Default 844.
+  --selector <css>        Scope inspection to one element + descendants.
+  --wait-strategy <name>  lazy-load (default) | auto | kaching-bundles | judge-me
+  --max-depth <n>         DOM walk max depth (default 8).
+  --max-children <n>      Max children kept per node (default 60).
+  --max-text <n>          Max chars of direct text per node (default 240).
+  --timeout <ms>          Per-step timeout (default 30000).
+  --help                  Show this message.
+
+Exit codes: 0=ok, 1=script error, 2=invalid args.
+`
+
+function fail(msg, code = 2) {
+  process.stderr.write(`[sb-inspect-live] ${msg}\n`)
+  process.exit(code)
+}
+
+function log(msg) {
+  process.stderr.write(`[sb-inspect-live] ${msg}\n`)
+}
+
+const { values } = parseArgs({
+  options: {
+    url: { type: 'string' },
+    'viewport-width': { type: 'string', default: '390' },
+    'viewport-height': { type: 'string', default: '844' },
+    selector: { type: 'string' },
+    'wait-strategy': { type: 'string', default: 'lazy-load' },
+    'output-dir': { type: 'string' },
+    'max-depth': { type: 'string', default: '8' },
+    'max-children': { type: 'string', default: '60' },
+    'max-text': { type: 'string', default: '240' },
+    timeout: { type: 'string', default: '30000' },
+    help: { type: 'boolean', default: false },
+  },
+  strict: false,
+})
+
+if (values.help) {
+  process.stdout.write(HELP)
+  process.exit(0)
+}
+
+if (!values.url) fail('missing --url')
+if (!values['output-dir']) fail('missing --output-dir')
+
+const URL = values.url
+const VIEWPORT_W = parseInt(values['viewport-width'], 10)
+const VIEWPORT_H = parseInt(values['viewport-height'], 10)
+const SELECTOR = values.selector || null
+const WAIT_STRATEGY = values['wait-strategy']
+const OUTPUT_DIR = resolve(values['output-dir'])
+const MAX_DEPTH = parseInt(values['max-depth'], 10)
+const MAX_CHILDREN = parseInt(values['max-children'], 10)
+const MAX_TEXT = parseInt(values['max-text'], 10)
+const TIMEOUT = parseInt(values.timeout, 10)
+
+if (!Number.isFinite(VIEWPORT_W) || !Number.isFinite(VIEWPORT_H)) fail('viewport must be numeric')
+
+// Known widget waits — selectors for third-party scripts whose content arrives
+// after the main page load. Hardcoded list, evolved as new widgets are encountered.
+const WIDGET_WAITS = {
+  'kaching-bundles': ['.kaching-bundles', '[class*="kaching"]', '[id*="kaching"]'],
+  'judge-me': ['.jdgm-rev-widg', '.jdgm-widget', '.jdgm-prev-badge', '[id*="jdgm"]'],
+}
+
+// Bot-challenge / blocked-page heuristics. If body text matches any of these
+// after settle, the script flags widgetBlocked: true so the orchestrator can
+// invoke Plan B instead of building from a placeholder.
+const BLOCK_PATTERNS = [
+  /just a moment/i,
+  /checking your browser/i,
+  /enable javascript( and cookies)? to continue/i,
+  /cloudflare/i,
+  /access denied/i,
+  /verifying you are human/i,
+  /please complete the security check/i,
+  /captcha/i,
+  /forbidden/i,
+]
+
+// Title-only block patterns (Cloudflare etc. often put the challenge in
+// <title> with a near-empty body — pattern #23 of the plan covers this).
+const BLOCK_TITLE_PATTERNS = [
+  /just a moment/i,
+  /attention required/i,
+  /access denied/i,
+  /forbidden/i,
+  /captcha/i,
+]
+
+async function main() {
+  await mkdir(OUTPUT_DIR, { recursive: true })
+
+  const screenshotPath = join(OUTPUT_DIR, 'screenshot.png')
+  const jsonPath = join(OUTPUT_DIR, 'inspection.json')
+
+  let chromium, devices, StealthPlugin
+  try {
+    ;({ chromium, devices } = await import('playwright-extra'))
+    StealthPlugin = (await import('puppeteer-extra-plugin-stealth')).default
+  } catch (err) {
+    process.stderr.write(
+      `[sb-inspect-live] missing dependency: ${err?.message || err}\n` +
+        `Install with: npm i playwright-extra puppeteer-extra-plugin-stealth playwright && npx playwright install chromium\n`,
+    )
+    process.exit(1)
+  }
+  chromium.use(StealthPlugin())
+
+  log(`launching chromium (stealth) for ${URL} @ ${VIEWPORT_W}x${VIEWPORT_H}`)
+
+  const browser = await chromium.launch({ headless: true })
+
+  // Use Playwright's iPhone 14 device profile as the base, but force the requested
+  // viewport so mobile-first 390 default is honored even if the device profile differs.
+  const iphone = devices['iPhone 14'] || {}
+  const context = await browser.newContext({
+    ...iphone,
+    viewport: { width: VIEWPORT_W, height: VIEWPORT_H },
+    userAgent:
+      iphone.userAgent ||
+      'Mozilla/5.0 (iPhone; CPU iPhone OS 17_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Mobile/15E148 Safari/604.1',
+    deviceScaleFactor: iphone.deviceScaleFactor || 3,
+    isMobile: true,
+    hasTouch: true,
+    locale: 'en-US',
+  })
+
+  const page = await context.newPage()
+  page.setDefaultTimeout(TIMEOUT)
+
+  const result = {
+    url: URL,
+    viewport: { width: VIEWPORT_W, height: VIEWPORT_H },
+    sectionType: 'unknown',
+    sectionBoundingBox: null,
+    tokens: {},
+    dom: [],
+    pseudoElements: [],
+    imgUrls: [],
+    screenshot: screenshotPath,
+    widgetBlocked: false,
+  }
+
+  try {
+    log('navigating (waitUntil: domcontentloaded)')
+    await page.goto(URL, { waitUntil: 'domcontentloaded', timeout: TIMEOUT })
+
+    // Initial settle. Many themes hydrate ~2-3s after DCL.
+    await page.waitForTimeout(3500)
+
+    // Step-scroll to trigger lazy-load observers. Range 0→12000 covers
+    // most long mobile pages; pages shorter than that scroll past the bottom
+    // and the browser clamps — harmless.
+    log('step-scrolling to trigger lazy-load')
+    await page.evaluate(async () => {
+      const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+      for (let y = 0; y <= 12000; y += 400) {
+        window.scrollTo(0, y)
+        await sleep(150)
+      }
+      window.scrollTo(0, 0)
+    })
+
+    // Force-eager: any <img loading="lazy"> that didn't intersect during scroll
+    // gets rewritten to eager and re-fetched. <picture> sources too.
+    log('forcing eager image fetch')
+    await page.evaluate(async () => {
+      const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+      const imgs = Array.from(document.querySelectorAll('img'))
+      for (const img of imgs) {
+        try {
+          img.loading = 'eager'
+          if (!img.complete || img.naturalWidth === 0) {
+            const src = img.currentSrc || img.src
+            if (src) {
+              img.src = ''
+              img.src = src
+            }
+          }
+        } catch (_) {}
+      }
+      await sleep(1200)
+    })
+
+    // Apply additional widget waits if requested.
+    const widgetsToWait =
+      WAIT_STRATEGY === 'auto'
+        ? Object.values(WIDGET_WAITS).flat()
+        : WIDGET_WAITS[WAIT_STRATEGY] || []
+
+    for (const sel of widgetsToWait) {
+      try {
+        await page.waitForSelector(sel, { timeout: 4000, state: 'attached' })
+        log(`widget appeared: ${sel}`)
+      } catch (_) {
+        // widget not present on this page — fine
+      }
+    }
+
+    // Final settle to let any post-widget reflow finish.
+    await page.waitForTimeout(800)
+
+    // Detect block / challenge pages with a composite signal — Pattern #23 of
+    // the plan. The old `bodyHtmlLen < 1024` heuristic alone caused false
+    // positives on legitimately minimalist pages (example.com 528B, info.cern.ch
+    // 646B). New rule:
+    //   1. extreme-tiny body (< 256B) → blocked (real pages always have at
+    //      least a meta/h1/p stack that exceeds this)
+    //   2. pattern in body text → blocked (covers Cloudflare/CAPTCHA prose)
+    //   3. pattern in <title> → blocked (Cloudflare often hides challenge in
+    //      the title alone with near-empty body)
+    //   4. body 256-1024B AND meaningful-children count < 2 → blocked
+    //      (small AND structurally bare = challenge page; small alone = OK)
+    const docState = await page.evaluate(() => ({
+      title: (document.title || '').slice(0, 200),
+      bodyText: (document.body?.innerText || '').slice(0, 4000),
+      bodyHtmlLen: (document.body?.innerHTML || '').length,
+      meaningfulChildren: (() => {
+        if (!document.body) return 0
+        let n = 0
+        for (const el of document.body.children) {
+          const tag = (el.tagName || '').toLowerCase()
+          if (tag === 'script' || tag === 'style' || tag === 'noscript') continue
+          n++
+        }
+        return n
+      })(),
+    }))
+    const blockedByBodyPattern = BLOCK_PATTERNS.some((re) => re.test(docState.bodyText))
+    const blockedByTitlePattern = BLOCK_TITLE_PATTERNS.some((re) => re.test(docState.title))
+    const extremeTiny = docState.bodyHtmlLen < 256
+    const smallAndBare =
+      docState.bodyHtmlLen >= 256 &&
+      docState.bodyHtmlLen < 1024 &&
+      docState.meaningfulChildren < 2
+    if (blockedByBodyPattern || blockedByTitlePattern || extremeTiny || smallAndBare) {
+      result.widgetBlocked = true
+      log(
+        `widgetBlocked=true (bodyPattern=${blockedByBodyPattern}, titlePattern=${blockedByTitlePattern}, extremeTiny=${extremeTiny}, smallAndBare=${smallAndBare}, bodyLen=${docState.bodyHtmlLen}, children=${docState.meaningfulChildren}, title=${JSON.stringify(docState.title.slice(0, 60))})`,
+      )
+    }
+
+    // Screenshot — full page if no selector, element-only otherwise.
+    log(`capturing screenshot → ${screenshotPath}`)
+    if (SELECTOR) {
+      const el = await page.$(SELECTOR)
+      if (!el) {
+        log(`selector ${SELECTOR} matched no elements; falling back to full-page screenshot`)
+        await page.screenshot({ path: screenshotPath, fullPage: true })
+      } else {
+        await el.screenshot({ path: screenshotPath })
+      }
+    } else {
+      await page.screenshot({ path: screenshotPath, fullPage: true })
+    }
+
+    // The big in-page extraction. Everything below runs in the browser context.
+    log('extracting DOM, tokens, pseudo-elements, image URLs')
+    const extracted = await page.evaluate(extractInPage, {
+      selector: SELECTOR,
+      maxDepth: MAX_DEPTH,
+      maxChildren: MAX_CHILDREN,
+      maxText: MAX_TEXT,
+    })
+
+    Object.assign(result, extracted)
+
+    // Sanity check — DOM came back empty even though body had content.
+    if (!result.widgetBlocked && Array.isArray(result.dom) && result.dom.length === 0 && docState.bodyHtmlLen > 1024) {
+      log('warning: extracted DOM is empty but body has content — selector may be wrong')
+    }
+  } catch (err) {
+    process.stderr.write(`[sb-inspect-live] error: ${err?.stack ? err.stack : err}\n`)
+    await browser.close().catch(() => {})
+    process.exit(1)
+  }
+
+  await browser.close()
+
+  // Persist + emit.
+  await writeFile(jsonPath, JSON.stringify(result, null, 2), 'utf8')
+
+  // Tiny screenshots are a soft signal of failed render even when not flagged.
+  try {
+    const sz = statSync(screenshotPath).size
+    if (sz < 4096 && !result.widgetBlocked) {
+      log(`warning: screenshot is only ${sz} bytes — page may not have rendered`)
+      result.widgetBlocked = true
+      result._reason = 'tiny_screenshot'
+      await writeFile(jsonPath, JSON.stringify(result, null, 2), 'utf8')
+    }
+  } catch (_) {}
+
+  process.stdout.write(JSON.stringify(result))
+  process.stdout.write('\n')
+}
+
+// =====================================================================
+// In-page extraction. This function is serialized to a string and runs
+// inside the browser via page.evaluate, so it must be self-contained.
+// =====================================================================
+function extractInPage({ selector, maxDepth, maxChildren, maxText }) {
+  const root = selector ? document.querySelector(selector) : document.body
+  if (!root) {
+    return {
+      sectionType: 'unknown',
+      sectionBoundingBox: null,
+      tokens: {},
+      dom: [],
+      pseudoElements: [],
+      imgUrls: [],
+    }
+  }
+
+  // ---- Section-type heuristic ----
+  // Class/role-based first; falls back to heading presence. Lives here for
+  // the standalone build; production framework will source from
+  // <plugin>/memory/patterns.md and pass via flags.
+  function classifySection(el) {
+    const cls = (typeof el.className === 'string' ? el.className : '').toLowerCase()
+    const tag = el.tagName.toLowerCase()
+    const id = (el.id || '').toLowerCase()
+    const blob = `${tag} ${cls} ${id}`
+    if (/\bhero\b/.test(blob)) return 'hero'
+    if (/\bbanner\b/.test(blob)) return 'banner'
+    if (/\bproduct(s|-grid|-list|-card)?\b/.test(blob)) return 'product-grid'
+    if (/\b(testimonial|review|jdgm)/.test(blob)) return 'testimonials'
+    if (/\b(cta|call.?to.?action)\b/.test(blob)) return 'cta'
+    if (/\bfooter\b/.test(blob) || tag === 'footer') return 'footer'
+    if (/\b(header|nav|navbar)\b/.test(blob) || tag === 'header' || tag === 'nav') return 'header'
+    if (/\bfeature/.test(blob)) return 'features'
+    if (/\b(faq|accordion)\b/.test(blob)) return 'faq'
+    if (/\b(bundle|kaching)\b/.test(blob)) return 'bundle'
+    if (/\bgallery\b/.test(blob)) return 'gallery'
+    return null
+  }
+
+  // ---- Computed-style picker ----
+  // Whitelist of properties we care about. Reading getComputedStyle is cheap;
+  // building giant objects is not — so we stick to tokens that drive layout
+  // and visual fidelity for downstream reconstruction.
+  const TYPO_PROPS = [
+    'font-family',
+    'font-size',
+    'font-weight',
+    'font-style',
+    'line-height',
+    'letter-spacing',
+    'text-transform',
+    'text-align',
+    'color',
+  ]
+  const BOX_PROPS = [
+    'display',
+    'position',
+    'top',
+    'right',
+    'bottom',
+    'left',
+    'width',
+    'height',
+    'max-width',
+    'min-height',
+    'margin',
+    'padding',
+    'gap',
+    'flex-direction',
+    'justify-content',
+    'align-items',
+    'flex-wrap',
+    'grid-template-columns',
+    'grid-template-rows',
+    'overflow',
+    'z-index',
+  ]
+  const VISUAL_PROPS = [
+    'background-color',
+    'background-image',
+    'background-size',
+    'background-position',
+    'background-repeat',
+    'border',
+    'border-radius',
+    'box-shadow',
+    'opacity',
+    'transform',
+    'filter',
+  ]
+  const PSEUDO_PROPS = [
+    'content',
+    'color',
+    'background-color',
+    'background-image',
+    'font-size',
+    'font-weight',
+    'position',
+    'top',
+    'right',
+    'bottom',
+    'left',
+    'width',
+    'height',
+    'transform',
+    'opacity',
+    'border-radius',
+    'box-shadow',
+    'display',
+  ]
+
+  function pick(style, props) {
+    const out = {}
+    for (const p of props) {
+      const v = style.getPropertyValue(p)
+      if (v && v !== 'normal' && v !== 'auto') out[p] = v.trim()
+    }
+    return out
+  }
+
+  function bbox(el) {
+    const r = el.getBoundingClientRect()
+    return {
+      x: Math.round(r.x + window.scrollX),
+      y: Math.round(r.y + window.scrollY),
+      w: Math.round(r.width),
+      h: Math.round(r.height),
+    }
+  }
+
+  function directText(el) {
+    let t = ''
+    for (const n of el.childNodes) {
+      if (n.nodeType === 3) t += n.nodeValue
+    }
+    t = t.replace(/\s+/g, ' ').trim()
+    if (t.length > maxText) t = `${t.slice(0, maxText)}…`
+    return t
+  }
+
+  // Skip script/style/noscript/template — they don't contribute to visual output.
+  const SKIP_TAGS = new Set(['script', 'style', 'noscript', 'template', 'meta', 'link'])
+
+  function walk(el, depth) {
+    if (depth > maxDepth) return null
+    if (SKIP_TAGS.has(el.tagName.toLowerCase())) return null
+    const style = window.getComputedStyle(el)
+    if (style.display === 'none' || style.visibility === 'hidden') return null
+
+    const node = {
+      tag: el.tagName.toLowerCase(),
+      classes: typeof el.className === 'string' ? el.className.split(/\s+/).filter(Boolean) : [],
+      id: el.id || null,
+      attrs: {},
+      text: directText(el),
+      bbox: bbox(el),
+      computed: {
+        ...pick(style, TYPO_PROPS),
+        ...pick(style, BOX_PROPS),
+        ...pick(style, VISUAL_PROPS),
+      },
+      children: [],
+    }
+
+    // Capture salient attributes only — keeps payload small while preserving
+    // semantic info the builder needs.
+    for (const name of ['href', 'src', 'srcset', 'alt', 'role', 'aria-label', 'data-section-id', 'data-section-type', 'data-block-id']) {
+      const v = el.getAttribute?.(name)
+      if (v) node.attrs[name] = v
+    }
+
+    let count = 0
+    for (const child of el.children) {
+      if (count >= maxChildren) {
+        node.children.push({ tag: '_truncated_', remaining: el.children.length - count })
+        break
+      }
+      const c = walk(child, depth + 1)
+      if (c) {
+        node.children.push(c)
+        count++
+      }
+    }
+
+    return node
+  }
+
+  // ---- Pseudo-elements walk ----
+  // For every visible element, check ::before and ::after. Only keep those
+  // with non-empty content — getComputedStyle returns 'none' for absent
+  // pseudo-elements, so this filters automatically.
+  const pseudoElements = []
+  function pseudoSelectorFor(el) {
+    if (el.id) return `#${el.id}`
+    const cls = typeof el.className === 'string' ? el.className.trim().split(/\s+/).filter(Boolean) : []
+    if (cls.length) return `${el.tagName.toLowerCase()}.${cls.slice(0, 3).join('.')}`
+    return el.tagName.toLowerCase()
+  }
+  function walkPseudo(el) {
+    if (SKIP_TAGS.has(el.tagName.toLowerCase())) return
+    for (const which of ['::before', '::after']) {
+      try {
+        const ps = window.getComputedStyle(el, which)
+        const content = ps.getPropertyValue('content')
+        if (content && content !== 'none' && content !== 'normal') {
+          pseudoElements.push({
+            selector: pseudoSelectorFor(el),
+            pseudo: which,
+            content,
+            computed: pick(ps, PSEUDO_PROPS),
+          })
+        }
+      } catch (_) {}
+    }
+    for (const child of el.children) walkPseudo(child)
+  }
+
+  // ---- Image URL collection ----
+  const seen = new Set()
+  const imgUrls = []
+  function nearestSection(el) {
+    let cur = el
+    while (cur && cur !== document.body) {
+      const cls = (typeof cur.className === 'string' ? cur.className : '').toLowerCase()
+      if (cur.id || /section|hero|banner|footer|header|product|testimonial|gallery|feature|faq|cta|bundle/.test(cls)) {
+        return cur.id || cls.split(/\s+/).filter(Boolean)[0] || cur.tagName.toLowerCase()
+      }
+      cur = cur.parentElement
+    }
+    return 'page'
+  }
+  function pushImg(url, type, contextEl, alt) {
+    if (!url) return
+    const trimmed = url.trim()
+    if (!trimmed || trimmed.startsWith('data:')) return
+    let abs
+    try {
+      abs = new URL(trimmed, location.href).toString()
+    } catch (_) {
+      return
+    }
+    const key = `${type}|${abs}`
+    if (seen.has(key)) return
+    seen.add(key)
+    imgUrls.push({
+      url: abs,
+      type,
+      context: nearestSection(contextEl),
+      alt: alt || '',
+      bbox: bbox(contextEl),
+    })
+  }
+  // <img> elements
+  for (const img of root.querySelectorAll('img')) {
+    pushImg(img.currentSrc || img.src, 'img', img, img.alt)
+    if (img.srcset) {
+      for (const part of img.srcset.split(',')) {
+        const u = part.trim().split(/\s+/)[0]
+        pushImg(u, 'img-srcset', img, img.alt)
+      }
+    }
+  }
+  // <source> inside <picture>
+  for (const source of root.querySelectorAll('source')) {
+    if (source.srcset) {
+      for (const part of source.srcset.split(',')) {
+        const u = part.trim().split(/\s+/)[0]
+        pushImg(u, 'source-srcset', source.parentElement || source, source.getAttribute('alt') || '')
+      }
+    }
+    if (source.src) pushImg(source.src, 'source', source.parentElement || source, '')
+  }
+  // background-image on every visible element
+  const allEls = root === document.body ? document.querySelectorAll('*') : root.querySelectorAll('*')
+  const elsToScan = root === document.body ? [...allEls] : [root, ...allEls]
+  for (const el of elsToScan) {
+    const bg = window.getComputedStyle(el).getPropertyValue('background-image')
+    if (!bg || bg === 'none') continue
+    const matches = bg.matchAll(/url\((['"]?)([^'")]+)\1\)/g)
+    for (const m of matches) {
+      pushImg(m[2], 'background', el, el.getAttribute('alt') || '')
+    }
+  }
+
+  // ---- Token aggregation ----
+  // Pick representative elements and capture the typography/color/layout
+  // signature. These feed sb-build-output's preset-resolution pass.
+  function token(el, props) {
+    if (!el) return null
+    return pick(window.getComputedStyle(el), props)
+  }
+  const firstButton = root.querySelector('button, .btn, [role="button"], a.button, a.btn')
+  const firstContainer = root.querySelector('.container, .wrapper, main, section')
+  const tokens = {
+    typography: {
+      h1: token(root.querySelector('h1'), TYPO_PROPS),
+      h2: token(root.querySelector('h2'), TYPO_PROPS),
+      h3: token(root.querySelector('h3'), TYPO_PROPS),
+      body: token(root.querySelector('p') || root, TYPO_PROPS),
+      button: token(firstButton, TYPO_PROPS),
+      link: token(root.querySelector('a'), TYPO_PROPS),
+    },
+    colors: {
+      background: window.getComputedStyle(document.body).getPropertyValue('background-color').trim(),
+      text: window.getComputedStyle(document.body).getPropertyValue('color').trim(),
+      primary: firstButton ? window.getComputedStyle(firstButton).getPropertyValue('background-color').trim() : null,
+      accent: token(root.querySelector('a'), ['color'])?.color || null,
+    },
+    layout: {
+      container: token(firstContainer, ['max-width', 'padding', 'margin', 'width']),
+      section: token(root, ['padding', 'margin', 'gap']),
+    },
+  }
+
+  // ---- Section element + bounding box ----
+  // The full-page screenshot covers the whole document, so a sectionType label
+  // alone leaves the comparator with no way to crop the live to match a
+  // section-only build. Anti-pattern #10. Surface the actual section bbox so
+  // the comparator can extract it before pixelmatch.
+  //
+  // Rules:
+  //  - With explicit --selector, the live screenshot is element-only already
+  //    (page.$(selector).screenshot at line ~236), so no crop is needed and
+  //    sectionBoundingBox is null.
+  //  - Without --selector, search root → descendants for the first element
+  //    with a known section class/tag signature; expose its document-relative
+  //    bbox in CSS pixels.
+  //  - If only the h1 fallback fires (sectionType=hero by heading presence),
+  //    bbox stays null — we don't know which subtree is "the hero" with
+  //    enough confidence to crop on it.
+  function findSectionAndBox(rootEl, hasExplicitSelector) {
+    if (hasExplicitSelector) {
+      const direct = classifySection(rootEl)
+      const sectionType = direct || (rootEl.querySelector('h1') ? 'hero' : 'section')
+      return { sectionType, sectionBoundingBox: null }
+    }
+    const direct = classifySection(rootEl)
+    if (direct) {
+      return { sectionType: direct, sectionBoundingBox: bbox(rootEl) }
+    }
+    const queue = [...rootEl.children]
+    while (queue.length) {
+      const el = queue.shift()
+      if (SKIP_TAGS.has(el.tagName.toLowerCase())) continue
+      const t = classifySection(el)
+      if (t) {
+        return { sectionType: t, sectionBoundingBox: bbox(el) }
+      }
+      for (const c of el.children) queue.push(c)
+    }
+    if (rootEl.querySelector('h1')) {
+      return { sectionType: 'hero', sectionBoundingBox: null }
+    }
+    return { sectionType: 'section', sectionBoundingBox: null }
+  }
+
+  walkPseudo(root)
+  const dom = [walk(root, 0)].filter(Boolean)
+  const { sectionType, sectionBoundingBox } = findSectionAndBox(root, !!selector)
+
+  return { sectionType, sectionBoundingBox, tokens, dom, pseudoElements, imgUrls }
+}
+
+main().catch((err) => {
+  process.stderr.write(`[sb-inspect-live] fatal: ${err?.stack ? err.stack : err}\n`)
+  process.exit(1)
+})