similarbuild 0.1.0

package/templates/skills/sb-validate-render/scripts/validate-render.mjs

@@ -0,0 +1,645 @@
+#!/usr/bin/env node
+// validate-render.mjs — Render a built fragment locally with the destination's
+// theme reset injected, capture a screenshot, and probe key tokens + geometry.
+//
+// This closes the build → validate loop for SimilarBuild: take whatever
+// `sb-build-wp` (HTML) or a future `sb-build-shopify` (Liquid) produced,
+// simulate what happens when the user pastes it into the destination CMS by
+// wrapping with the destination's blanket selectors and forcing the destination's
+// !important-laced typography rules over the fragment, then measure how the
+// browser actually renders it.
+//
+// Mobile-first: viewport 390x844 by default. Uses Playwright `setContent` (NOT
+// `goto`) — the HTML is in hand. Outputs a single JSON object to stdout AND
+// writes render.json + screenshot.png into --output-dir. Logs progress to stderr.
+
+import { parseArgs } from 'node:util'
+import { mkdir, writeFile, readFile, access } from 'node:fs/promises'
+import { join, resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { statSync } from 'node:fs'
+
+// playwright, liquidjs, js-yaml are imported lazily inside main() so --help and
+// arg validation work without the deps installed, and so the Shopify-only deps
+// are not required for the WP path.
+
+const HELP = `
+validate-render.mjs — Render a built fragment locally with theme reset injected.
+
+Required:
+  --file <path>           HTML (preset=wp-elementor) or Liquid (preset=shopify-section).
+  --preset <name>         wp-elementor | shopify-section
+  --output-dir <dir>      Directory for screenshot.png + render.json.
+
+Optional:
+  --viewport-width <px>   Default 390 (mobile-first).
+  --viewport-height <px>  Default 844.
+  --preset-yaml <path>    Override preset YAML (otherwise auto-detects
+                          <plugin>/presets/{preset}.yaml, falls back to baked-in).
+  --selector <css>        Scope token probing + section bbox to one element.
+                          Default: the wrapper root (.elementor or section).
+  --assets-map-path <path>  (preset=shopify-section only) Path to the
+                          assets-map.json from sb-extract-assets. When provided,
+                          image_picker settings without 'default' get populated
+                          from matching assetsMap entries (by context heuristic)
+                          so the rendered fragment shows real imagery instead of
+                          the {% else %} placeholder. Pattern #32 of the plan.
+  --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-validate-render] ${msg}\n`)
+  process.exit(code)
+}
+
+function log(msg) {
+  process.stderr.write(`[sb-validate-render] ${msg}\n`)
+}
+
+const { values } = parseArgs({
+  options: {
+    file: { type: 'string' },
+    preset: { type: 'string' },
+    'viewport-width': { type: 'string', default: '390' },
+    'viewport-height': { type: 'string', default: '844' },
+    'preset-yaml': { type: 'string' },
+    'output-dir': { type: 'string' },
+    selector: { type: 'string' },
+    'assets-map-path': { type: 'string' },
+    timeout: { type: 'string', default: '30000' },
+    help: { type: 'boolean', default: false },
+  },
+  strict: false,
+})
+
+if (values.help) {
+  process.stdout.write(HELP)
+  process.exit(0)
+}
+
+if (!values.file) fail('missing --file')
+if (!values.preset) fail('missing --preset')
+if (!values['output-dir']) fail('missing --output-dir')
+
+const FILE = resolve(values.file)
+const PRESET = values.preset
+const VIEWPORT_W = parseInt(values['viewport-width'], 10)
+const VIEWPORT_H = parseInt(values['viewport-height'], 10)
+const PRESET_YAML = values['preset-yaml'] ? resolve(values['preset-yaml']) : null
+const OUTPUT_DIR = resolve(values['output-dir'])
+const SELECTOR = values.selector || null
+const ASSETS_MAP_PATH = values['assets-map-path'] ? resolve(values['assets-map-path']) : null
+const TIMEOUT = parseInt(values.timeout, 10)
+
+if (!Number.isFinite(VIEWPORT_W) || !Number.isFinite(VIEWPORT_H)) fail('viewport must be numeric')
+if (PRESET !== 'wp-elementor' && PRESET !== 'shopify-section') {
+  fail(`unknown preset "${PRESET}" — expected wp-elementor or shopify-section`)
+}
+
+// ============================================================================
+// Hardcoded preset fallbacks. Populated when <plugin>/presets/{preset}.yaml is
+// missing — that file gets written by item #14 of the visual-migration plan,
+// and users can customize it for their specific theme (Astra, Hello, custom Dawn).
+// Keep these in sync with the plan brief: aggressive enough to simulate what a
+// real theme actually does to a pasted fragment.
+// ============================================================================
+const FALLBACK_PRESETS = {
+  'wp-elementor': {
+    wrapper: { tag: 'div', class: 'elementor' },
+    reset_css: `
+.elementor, .elementor * { font-weight: 300 !important; font-size: 18px !important; font-family: 'Roboto', sans-serif !important; }
+.elementor h1, .elementor h2, .elementor h3 { font-weight: 300 !important; font-size: 24px !important; }
+.elementor img, img { max-width: 100% !important; height: auto !important; border-radius: 0 !important; }
+.elementor button, button { background: transparent !important; border: 0 !important; padding: 0 !important; }
+`.trim(),
+    // Fonts injected before reset so Roboto is actually available when the reset
+    // forces font-family. Without this, the reset names a font the page doesn't have.
+    head_extras: `<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;700&display=swap">`,
+    // Default selector for token probing + section bbox if --selector not passed.
+    default_probe_root: '.elementor',
+  },
+  'shopify-section': {
+    wrapper: { tag: 'div', class: 'page-width' },
+    reset_css: `
+body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; font-size: 16px; line-height: 1.5; color: rgb(18, 18, 18); margin: 0; }
+.page-width { max-width: 120rem; padding: 0 1.5rem; margin: 0 auto; box-sizing: border-box; }
+h1 { font-size: 4rem; font-weight: 400; line-height: 1.1; letter-spacing: -0.05rem; margin: 0 0 1.5rem; }
+h2 { font-size: 3rem; font-weight: 400; line-height: 1.15; letter-spacing: -0.04rem; margin: 0 0 1.25rem; }
+h3 { font-size: 2.4rem; font-weight: 400; line-height: 1.2; letter-spacing: -0.03rem; margin: 0 0 1rem; }
+button, .button { background: rgb(18, 18, 18); color: rgb(255, 255, 255); border: 0.1rem solid rgb(18, 18, 18); border-radius: 0; padding: 1.5rem 3rem; font-size: 1.5rem; font-weight: 500; cursor: pointer; }
+img { max-width: 100%; height: auto; display: block; }
+* { box-sizing: border-box; }
+html { font-size: 62.5%; }
+`.trim(),
+    head_extras: '',
+    default_probe_root: '.page-width',
+  },
+}
+
+async function loadPreset() {
+  // Resolve order: --preset-yaml override → <plugin>/presets/{preset}.yaml → hardcoded.
+  const candidatePaths = []
+  if (PRESET_YAML) candidatePaths.push(PRESET_YAML)
+  // <plugin> = two levels up from this script's <skill-root>/scripts/.
+  // .claude/skills/sb-validate-render/scripts/ → .claude/presets/{preset}.yaml
+  const here = dirname(fileURLToPath(import.meta.url))
+  const pluginPresets = resolve(here, '..', '..', '..', 'presets', `${PRESET}.yaml`)
+  candidatePaths.push(pluginPresets)
+
+  for (const p of candidatePaths) {
+    try {
+      await access(p)
+      log(`loading preset YAML: ${p}`)
+      const raw = await readFile(p, 'utf8')
+      let yaml
+      try {
+        yaml = (await import('js-yaml')).default
+      } catch (_) {
+        log(`js-yaml not installed; cannot parse ${p} — falling back to hardcoded preset`)
+        break
+      }
+      const parsed = yaml.load(raw)
+      // Merge with hardcoded so a partial YAML override still works.
+      return { ...FALLBACK_PRESETS[PRESET], ...parsed }
+    } catch (_) {
+      // file doesn't exist — try next
+    }
+  }
+  log(`using hardcoded fallback preset for ${PRESET}`)
+  return FALLBACK_PRESETS[PRESET]
+}
+
+// ============================================================================
+// Liquid rendering. Only invoked when preset=shopify-section.
+// Parses {% schema %}...{% endschema %} JSON, builds mock context from setting
+// defaults + presets[0].blocks (or schema.default.blocks), strips the schema
+// from source, hands the rest to liquidjs.
+// ============================================================================
+function extractSchema(liquidSrc) {
+  const m = liquidSrc.match(/\{%-?\s*schema\s*-?%\}([\s\S]*?)\{%-?\s*endschema\s*-?%\}/)
+  if (!m) return { schema: null, body: liquidSrc }
+  let schema = null
+  try {
+    schema = JSON.parse(m[1])
+  } catch (err) {
+    log(`schema JSON parse failed: ${err.message} — proceeding with empty mock context`)
+  }
+  const body = liquidSrc.slice(0, m.index) + liquidSrc.slice(m.index + m[0].length)
+  return { schema, body }
+}
+
+// Match an image_picker setting (no default) to an entry in assetsMap.assets[]
+// using context heuristics. Setting id keywords map to known context substrings
+// emitted by sb-inspect-live (e.g. "ai-hero" for the hero, "ai-hdr" for header
+// logo, "ai-fp__gallery" for product gallery). Returns the matching asset or
+// null. Pattern #32 of the plan: a placeholder mock against a real photo
+// inflates diff% by ~30pp that isn't actionable; populating the mock with the
+// real asset that the merchant will eventually pick removes the noise.
+const IMAGE_PICKER_ID_HEURISTICS = [
+  { idRe: /(^|[_-])(hero|banner|cover)([_-]|$)/i, ctxKeywords: ['hero', 'ai-hero', 'banner', 'cover'] },
+  { idRe: /^(hero|banner|cover)(_image)?$/i, ctxKeywords: ['hero', 'ai-hero', 'banner', 'cover'] },
+  { idRe: /(^|[_-])(logo|brand)([_-]|$)/i, ctxKeywords: ['header', 'ai-hdr', 'logo', 'brand'] },
+  { idRe: /^(logo|brand)$/i, ctxKeywords: ['header', 'ai-hdr', 'logo', 'brand'] },
+  { idRe: /(^|[_-])(product|gallery|featured)([_-]|$)/i, ctxKeywords: ['ai-fp__gallery', 'product', 'gallery', 'featured'] },
+  { idRe: /^(product_image|gallery_image|featured_image)$/i, ctxKeywords: ['ai-fp__gallery', 'product', 'gallery', 'featured'] },
+]
+
+function findAssetForImagePicker(settingId, assetsMap) {
+  if (!settingId || !assetsMap || !assetsMap.assets || typeof assetsMap.assets !== 'object') return null
+  const id = String(settingId).toLowerCase()
+  // sb-extract-assets emits assets as Object (URL → asset map), not Array.
+  const assetEntries = Array.isArray(assetsMap.assets) ? assetsMap.assets : Object.values(assetsMap.assets)
+  for (const rule of IMAGE_PICKER_ID_HEURISTICS) {
+    if (!rule.idRe.test(id)) continue
+    for (const a of assetEntries) {
+      const c = String(a?.context || '').toLowerCase()
+      if (!c) continue
+      if (rule.ctxKeywords.some((kw) => c.includes(kw))) return a
+    }
+  }
+  // Fallback: first asset with non-empty context.
+  for (const a of assetEntries) {
+    if (String(a?.context || '').trim()) return a
+  }
+  return null
+}
+
+const MIME_BY_EXT = {
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  png: 'image/png',
+  webp: 'image/webp',
+  avif: 'image/avif',
+  gif: 'image/gif',
+  svg: 'image/svg+xml',
+}
+
+async function readAssetAsDataUrl(asset) {
+  if (!asset || !asset.localPath) return null
+  try {
+    const buf = await readFile(asset.localPath)
+    const ext = String(asset.ext || asset.localPath.split('.').pop() || 'jpg').toLowerCase()
+    const mime = MIME_BY_EXT[ext] || 'image/jpeg'
+    return `data:${mime};base64,${buf.toString('base64')}`
+  } catch (err) {
+    log(`failed to read asset ${asset.localPath}: ${err.message}`)
+    return null
+  }
+}
+
+function buildMockContext(schema) {
+  if (!schema) return { section: { id: 'mock', settings: {}, blocks: [] } }
+  const settings = {}
+  for (const s of schema.settings || []) {
+    if (s?.id && 'default' in s) settings[s.id] = s.default
+  }
+  // Prefer presets[0].blocks (storefront-installable preset) then schema.default.blocks.
+  const rawBlocks =
+    schema.presets?.[0]?.blocks ||
+    schema.default?.blocks ||
+    []
+  const blockTypeDefaults = {}
+  for (const b of schema.blocks || []) {
+    if (!b?.type) continue
+    const bs = {}
+    for (const s of b.settings || []) {
+      if (s?.id && 'default' in s) bs[s.id] = s.default
+    }
+    blockTypeDefaults[b.type] = bs
+  }
+  const blocks = rawBlocks.map((b, i) => ({
+    id: b.id || `block-${i}`,
+    type: b.type,
+    settings: { ...(blockTypeDefaults[b.type] || {}), ...(b.settings || {}) },
+    shopify_attributes: '',
+  }))
+  return {
+    section: { id: 'mock', settings, blocks, blocks_count: blocks.length },
+  }
+}
+
+async function renderLiquid(liquidSrc, assetsMap = null) {
+  let Liquid
+  try {
+    ;({ Liquid } = await import('liquidjs'))
+  } catch (_) {
+    process.stderr.write(
+      `[sb-validate-render] liquidjs is required for preset=shopify-section but not installed.\n` +
+        `Install with: npm i liquidjs\n`,
+    )
+    process.exit(1)
+  }
+  const { schema, body } = extractSchema(liquidSrc)
+  const ctx = buildMockContext(schema)
+  // Pattern #32 of the plan: when assetsMap is supplied, populate image_picker
+  // settings without 'default' from matching assetsMap entries (data-URL inline).
+  // Without this, the {% else %} branch fires and the rendered fragment shows a
+  // neutral placeholder where the live page shows a real photo, inflating the
+  // pixel diff by tens of points with no actionable fix.
+  const mockResult = { populated: [], skipped: [] }
+  if (assetsMap && schema && Array.isArray(schema.settings)) {
+    for (const s of schema.settings) {
+      if (s?.type !== 'image_picker') continue
+      if (!s.id) continue
+      if ('default' in s) continue
+      const asset = findAssetForImagePicker(s.id, assetsMap)
+      if (!asset) {
+        mockResult.skipped.push(s.id)
+        continue
+      }
+      const dataUrl = await readAssetAsDataUrl(asset)
+      if (!dataUrl) {
+        mockResult.skipped.push(s.id)
+        continue
+      }
+      ctx.section.settings[s.id] = dataUrl
+      mockResult.populated.push(s.id)
+    }
+    if (mockResult.populated.length) {
+      log(`mock context: populated image_picker [${mockResult.populated.join(', ')}] from assetsMap`)
+    }
+    if (mockResult.skipped.length) {
+      log(`mock context: skipped image_picker [${mockResult.skipped.join(', ')}] (no matching asset)`)
+    }
+  }
+  // Normalize Shopify-native block tags ({% style %}, {% javascript %},
+  // {% stylesheet %}) into plain HTML wrappers so vanilla liquidjs can parse
+  // them. Inner {{ ... }} and {% if %} expressions are preserved and still
+  // evaluated. Without this, liquidjs throws `tag "style" not found` and the
+  // entire Shopify render path is dead.
+  const normalizedBody = body
+    .replace(/\{%-?\s*style\s*-?%\}/g, '<style>')
+    .replace(/\{%-?\s*endstyle\s*-?%\}/g, '</style>')
+    .replace(/\{%-?\s*stylesheet(?:\s+[^%]*?)?-?%\}/g, '<style>')
+    .replace(/\{%-?\s*endstylesheet\s*-?%\}/g, '</style>')
+    .replace(/\{%-?\s*javascript\s*-?%\}/g, '<script>')
+    .replace(/\{%-?\s*endjavascript\s*-?%\}/g, '</script>')
+  const engine = new Liquid({ strictFilters: false, strictVariables: false })
+  // Minimal Shopify filter shims so common storefront filters don't blow up the render.
+  engine.registerFilter('asset_url', (v) => `/assets/${v || ''}`)
+  engine.registerFilter('img_url', (v) => v || '')
+  engine.registerFilter('img_tag', (v, alt = '') => `<img src="${v || ''}" alt="${alt}">`)
+  engine.registerFilter('image_url', (v) => v || '')
+  engine.registerFilter('image_tag', (v, alt = '') => `<img src="${v || ''}" alt="${alt}">`)
+  engine.registerFilter('money', (v) => `$${v || 0}`)
+  engine.registerFilter('t', (v) => v)
+  engine.registerFilter('default', (v, d) => (v == null || v === '' ? d : v))
+  engine.registerFilter('escape', (v) => String(v ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]))
+  engine.registerFilter('handleize', (v) => String(v ?? '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''))
+  const html = await engine.parseAndRender(normalizedBody, ctx)
+  return { html, mockContext: mockResult }
+}
+
+async function main() {
+  await mkdir(OUTPUT_DIR, { recursive: true })
+
+  const screenshotPath = join(OUTPUT_DIR, 'screenshot.png')
+  const jsonPath = join(OUTPUT_DIR, 'render.json')
+
+  const preset = await loadPreset()
+
+  log(`reading source file: ${FILE}`)
+  const sourceRaw = await readFile(FILE, 'utf8')
+
+  // Pattern #32: load assets-map.json when --assets-map-path was supplied so
+  // image_picker mock-context can resolve to real assets instead of placeholder.
+  let assetsMap = null
+  if (ASSETS_MAP_PATH && PRESET === 'shopify-section') {
+    try {
+      const raw = await readFile(ASSETS_MAP_PATH, 'utf8')
+      assetsMap = JSON.parse(raw)
+      log(`loaded assets-map: ${ASSETS_MAP_PATH} (${(assetsMap.assets || []).length} assets)`)
+    } catch (err) {
+      log(`failed to load assets-map "${ASSETS_MAP_PATH}": ${err.message} — proceeding without`)
+    }
+  }
+
+  let bodyContent
+  let mockContext = null
+  if (PRESET === 'shopify-section') {
+    log('rendering Liquid with mock schema-default context')
+    const rendered = await renderLiquid(sourceRaw, assetsMap)
+    bodyContent = rendered.html
+    mockContext = rendered.mockContext
+  } else {
+    bodyContent = sourceRaw
+  }
+
+  // Wrap with the preset's destination wrapper so the destination's blanket
+  // selectors (.elementor *, .page-width) actually match the fragment.
+  const wrapTag = preset.wrapper?.tag || 'div'
+  const wrapClass = preset.wrapper?.class || ''
+  const wrapped = `<${wrapTag} class="${wrapClass}">\n${bodyContent}\n</${wrapTag}>`
+
+  const fullHtml = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>sb-validate-render</title>
+${preset.head_extras || ''}
+<style id="sb-theme-reset">
+${preset.reset_css || ''}
+</style>
+</head>
+<body>
+${wrapped}
+</body>
+</html>`
+
+  let chromium
+  try {
+    ;({ chromium } = await import('playwright'))
+  } catch (err) {
+    process.stderr.write(
+      `[sb-validate-render] missing dependency: ${err?.message || err}\n` +
+        `Install with: npm i playwright && npx playwright install chromium\n`,
+    )
+    process.exit(1)
+  }
+
+  log(`launching chromium @ ${VIEWPORT_W}x${VIEWPORT_H}`)
+  const browser = await chromium.launch({ headless: true })
+  const context = await browser.newContext({
+    viewport: { width: VIEWPORT_W, height: VIEWPORT_H },
+    // DPR 3 to match sb-inspect-live's iPhone 14 capture (Pattern #22 in plan):
+    // when these diverge, sb-compare-visual sees positional drift dominate the
+    // pixel diff even with token-perfect builds.
+    deviceScaleFactor: 3,
+    isMobile: true,
+    hasTouch: true,
+    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',
+  })
+  const page = await context.newPage()
+  page.setDefaultTimeout(TIMEOUT)
+
+  const probeRoot = SELECTOR || preset.default_probe_root || 'body'
+  const result = {
+    file: FILE,
+    preset: PRESET,
+    viewport: { width: VIEWPORT_W, height: VIEWPORT_H },
+    probeRoot,
+    screenshot: screenshotPath,
+    tokens: {},
+    geometry: {},
+    warnings: [],
+    mockContext,
+  }
+
+  try {
+    log('setContent (no goto — fragment is in hand)')
+    await page.setContent(fullHtml, { waitUntil: 'load', timeout: TIMEOUT })
+
+    // Wait for Google Fonts (preset.head_extras may inject a stylesheet) so the
+    // typography measurement reflects the loaded font, not the system fallback.
+    try {
+      await page.evaluate(() => document.fonts?.ready)
+    } catch (_) {}
+    await page.waitForTimeout(400)
+
+    log(`capturing screenshot → ${screenshotPath}`)
+    await page.screenshot({ path: screenshotPath, fullPage: true })
+
+    log(`probing tokens + geometry from ${probeRoot}`)
+    const probed = await page.evaluate(probeInPage, { probeRoot })
+    Object.assign(result, probed)
+  } catch (err) {
+    process.stderr.write(`[sb-validate-render] error: ${err?.stack ? err.stack : err}\n`)
+    await browser.close().catch(() => {})
+    process.exit(1)
+  }
+
+  await browser.close()
+
+  // Sanity flag — tiny screenshots usually mean the page didn't render.
+  try {
+    const sz = statSync(screenshotPath).size
+    if (sz < 4096) {
+      result.warnings.push(`screenshot is only ${sz} bytes — render may have failed`)
+    }
+  } catch (_) {}
+
+  await writeFile(jsonPath, JSON.stringify(result, null, 2), 'utf8')
+  process.stdout.write(JSON.stringify(result))
+  process.stdout.write('\n')
+}
+
+// =====================================================================
+// In-page probe. Serialized to a string and runs inside the browser via
+// page.evaluate, so it must be self-contained.
+// =====================================================================
+function probeInPage({ probeRoot }) {
+  const root = document.querySelector(probeRoot) || document.body
+
+  function pick(el, props) {
+    if (!el) return null
+    const cs = getComputedStyle(el)
+    const out = {}
+    for (const p of props) {
+      const v = cs.getPropertyValue(p)
+      if (v) out[p] = v.trim()
+    }
+    return out
+  }
+
+  function bbox(el) {
+    if (!el) return null
+    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),
+    }
+  }
+
+  // Tokens — pick first-instance for each heading; aggregate stats for body/img.
+  const h1 = root.querySelector('h1')
+  const h2 = root.querySelector('h2')
+  const h3 = root.querySelector('h3')
+  const button = root.querySelector('button, .button, [role="button"]')
+
+  // Body probe must reflect the SCOPE's body-like typography, not the host
+  // <body> default. The Pattern #24 bug: probing document.body returned UA
+  // defaults ("Times New Roman", 16px) for any fragment whose scope had its
+  // own body-text rules, corrupting tokens.body in render.json. Search order:
+  //   1. first <p>/<span>/<div> inside scope that holds direct text content
+  //   2. the scope root itself
+  //   3. document.body (last-resort fallback)
+  function findBodyLikeInScope(scopeRoot) {
+    if (!scopeRoot || scopeRoot === document.body) return null
+    const candidates = scopeRoot.querySelectorAll('p, span, div, li')
+    for (const el of candidates) {
+      // "direct text content" = text inside this element that isn't just
+      // descendant whitespace; we accept anything ≥ 1 visible char.
+      let direct = ''
+      for (const node of el.childNodes) {
+        if (node.nodeType === 3) direct += node.nodeValue || ''
+      }
+      if (direct.replace(/\s+/g, '').length >= 1) return el
+    }
+    return null
+  }
+  const bodyEl = findBodyLikeInScope(root) || (root !== document.body ? root : document.body)
+  const bodyStyle = getComputedStyle(bodyEl)
+
+  // Image probing: report the first image's height + a per-image rundown so the
+  // orchestrator can spot the "default vs override" split (Anti-pattern #5 territory).
+  const imgs = Array.from(root.querySelectorAll('img'))
+  const imgReport = imgs.slice(0, 20).map((img) => {
+    const r = img.getBoundingClientRect()
+    const cs = getComputedStyle(img)
+    return {
+      src: img.getAttribute('src') || '',
+      alt: img.getAttribute('alt') || '',
+      computedHeight: cs.height,
+      computedMaxWidth: cs.maxWidth,
+      renderedW: Math.round(r.width),
+      renderedH: Math.round(r.height),
+      hasInlineStyle: !!img.getAttribute('style'),
+    }
+  })
+
+  // Container width: walk up from probe root looking for the first ancestor with
+  // an explicit max-width or width that's not 'none'/'auto'.
+  let containerEl = root
+  let containerWidth = null
+  while (containerEl && containerEl !== document.body) {
+    const cs = getComputedStyle(containerEl)
+    const mw = cs.maxWidth
+    const w = cs.width
+    if ((mw && mw !== 'none') || (w && w !== 'auto')) {
+      containerWidth = { maxWidth: mw, width: w, computedRenderedW: Math.round(containerEl.getBoundingClientRect().width) }
+      break
+    }
+    containerEl = containerEl.parentElement
+  }
+  if (!containerWidth) {
+    containerWidth = { maxWidth: 'none', width: 'auto', computedRenderedW: Math.round(root.getBoundingClientRect().width) }
+  }
+
+  // Geometry — total height, viewport overflow, first-section dims.
+  const docEl = document.documentElement
+  const totalHeight = Math.max(docEl.scrollHeight, document.body.scrollHeight)
+  const totalWidth = Math.max(docEl.scrollWidth, document.body.scrollWidth)
+  const viewportOverflow = totalWidth > window.innerWidth + 1
+
+  const sections = Array.from(document.querySelectorAll('section, .elementor-section, [class*="section"]')).slice(0, 6).map((s) => ({
+    tag: s.tagName.toLowerCase(),
+    classes: (typeof s.className === 'string' ? s.className : '').trim().split(/\s+/).filter(Boolean).slice(0, 8),
+    bbox: bbox(s),
+  }))
+
+  return {
+    tokens: {
+      h1: h1
+        ? { present: true, text: (h1.textContent || '').trim().slice(0, 80), ...pick(h1, ['font-size', 'font-weight', 'font-family', 'line-height', 'color']) }
+        : { present: false },
+      h2: h2
+        ? { present: true, text: (h2.textContent || '').trim().slice(0, 80), ...pick(h2, ['font-size', 'font-weight', 'font-family', 'line-height', 'color']) }
+        : { present: false },
+      h3: h3
+        ? { present: true, text: (h3.textContent || '').trim().slice(0, 80), ...pick(h3, ['font-size', 'font-weight', 'font-family', 'line-height', 'color']) }
+        : { present: false },
+      body: {
+        'font-size': bodyStyle.getPropertyValue('font-size').trim(),
+        'font-weight': bodyStyle.getPropertyValue('font-weight').trim(),
+        'font-family': bodyStyle.getPropertyValue('font-family').trim(),
+        'line-height': bodyStyle.getPropertyValue('line-height').trim(),
+        color: bodyStyle.getPropertyValue('color').trim(),
+      },
+      button: button
+        ? {
+            present: true,
+            text: (button.textContent || '').trim().slice(0, 60),
+            ...pick(button, ['height', 'min-height', 'padding', 'border', 'border-radius', 'background-color', 'color', 'font-size', 'font-weight']),
+            renderedH: Math.round(button.getBoundingClientRect().height),
+          }
+        : { present: false },
+      images: {
+        count: imgs.length,
+        sampled: imgReport,
+      },
+      container: containerWidth,
+    },
+    geometry: {
+      totalHeight,
+      totalWidth,
+      viewportInner: { width: window.innerWidth, height: window.innerHeight },
+      viewportOverflow,
+      probeRoot: bbox(root),
+      sections,
+    },
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`[sb-validate-render] fatal: ${err?.stack || err}\n`)
+  process.exit(1)
+})