similarbuild 0.1.0

package/templates/skills/sb-build-wp/scripts/build-wp.mjs

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+// build-wp.mjs — Plumbing for sb-build-wp.
+//
+// The LLM composes the HTML; this script handles the deterministic plumbing
+// around that composition: structural validation of the produced HTML, and
+// formatting + persistence to the output path.
+//
+// Two subcommands:
+//   validate --html-file <path>            Check structural rules, JSON to stdout.
+//                                          Exit 0 if all errors clean, 1 if errors.
+//   write --output-path <path>             Read HTML from stdin, optional prettier
+//                                          format (graceful skip if not installed),
+//                                          write to disk, JSON to stdout.
+//
+// Validation rules check the *mechanical* subset of the rules in
+// references/wp-build-rules.md — the parts that can be checked with regex.
+// Semantic correctness (correct pattern picked, defensive specificity actually
+// applied where it matters, alt text being meaningful) is the LLM's job.
+//
+// prettier is imported lazily and is OPTIONAL. If it's not installed, write
+// still succeeds — the HTML is just persisted unformatted.
+//
+// Exit codes: 0=ok, 1=script error, 2=invalid args, 3=validation failed.
+
+import { parseArgs } from 'node:util'
+import { mkdir, writeFile, readFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+
+const HELP = `
+build-wp.mjs — Validate and persist HTML produced by sb-build-wp.
+
+Subcommands:
+  validate --html-file <path>      Run structural lint on the HTML file.
+  write --output-path <path>       Read HTML from stdin, format if prettier
+                                   is available, write to <output-path>.
+
+Common flags:
+  --help                           Show this message.
+  --verbose                        Extra diagnostics to stderr.
+
+Exit codes: 0=ok, 1=script error, 2=invalid args, 3=validation failed.
+`
+
+function fail(msg, code = 2) {
+  process.stderr.write(`[sb-build-wp] ${msg}\n`)
+  process.exit(code)
+}
+
+function log(verbose, msg) {
+  if (verbose) process.stderr.write(`[sb-build-wp] ${msg}\n`)
+}
+
+async function readStdin() {
+  const chunks = []
+  for await (const chunk of process.stdin) chunks.push(chunk)
+  return Buffer.concat(chunks).toString('utf8')
+}
+
+// --- Validation rules ---------------------------------------------------------
+
+function findAll(re, str) {
+  const out = []
+  const flags = re.flags.includes('g') ? re.flags : `${re.flags}g`
+  const r = new RegExp(re.source, flags)
+  for (let m = r.exec(str); m !== null; m = r.exec(str)) {
+    out.push(m)
+  }
+  return out
+}
+
+function validateHtml(html) {
+  const errors = []
+  const warnings = []
+  const info = []
+
+  // 1. <style> block must exist.
+  if (!/<style\b[^>]*>[\s\S]*?<\/style>/i.test(html)) {
+    errors.push({
+      rule: 'missing-style-block',
+      message: 'No <style> block found. Output must be a self-contained fragment with scoped CSS.',
+    })
+  }
+
+  // 2. Every <img> must have alt attribute (decorative images use alt="").
+  const imgs = findAll(/<img\b[^>]*>/gi, html)
+  imgs.forEach((m, i) => {
+    if (!/\balt\s*=/i.test(m[0])) {
+      errors.push({
+        rule: 'img-missing-alt',
+        message: `<img> #${i + 1} is missing alt attribute. Decorative images must use alt="".`,
+        snippet: m[0].slice(0, 120),
+      })
+    }
+  })
+
+  // 3. Every <button> must have type= (anything other than missing — submit/button/reset all explicit is fine).
+  const buttons = findAll(/<button\b[^>]*>/gi, html)
+  buttons.forEach((m, i) => {
+    if (!/\btype\s*=/i.test(m[0])) {
+      errors.push({
+        rule: 'button-missing-type',
+        message: `<button> #${i + 1} is missing type attribute. Use type="button" unless intentionally a submit.`,
+        snippet: m[0].slice(0, 120),
+      })
+    }
+  })
+
+  // 4. Anti-pattern #8 — fabricated raster-as-SVG via inline data URI in <img src>.
+  imgs.forEach((m) => {
+    const srcMatch = /\bsrc\s*=\s*["']([^"']+)["']/i.exec(m[0])
+    if (srcMatch && /^data:image\/svg\+xml/i.test(srcMatch[1])) {
+      errors.push({
+        rule: 'fabricated-svg-data-uri',
+        message: 'Anti-pattern #8: <img src="data:image/svg+xml,..."> indicates a fabricated SVG. Use the real asset from assetsMap.',
+        snippet: `${srcMatch[1].slice(0, 80)}...`,
+      })
+    }
+  })
+
+  // 5. Anti-pattern #1 — 100vh used on a height-related property in CSS.
+  // Match height/min-height: 100vh (also catches 100 vh just in case).
+  const styleBlocks = findAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi, html)
+  const css = styleBlocks.map((m) => m[1]).join('\n')
+  const vhUses = findAll(/(min-height|height)\s*:\s*100vh\b/gi, css)
+  if (vhUses.length > 0) {
+    errors.push({
+      rule: 'hero-100vh',
+      message: `Anti-pattern #1: 100vh used on ${vhUses.length} height declaration(s). Use aspect-ratio + max-height instead.`,
+    })
+  }
+
+  // 6. Google Fonts stylesheet must include display=swap. Scope to stylesheet
+  // links pointing at fonts.googleapis.com/css — preconnect links to the same
+  // origin are not stylesheets and don't carry the swap parameter.
+  const allFontsLinks = findAll(/<link\b[^>]*>/gi, html).filter((m) =>
+    /\bhref\s*=\s*["'][^"']*fonts\.googleapis\.com\/css/i.test(m[0])
+  )
+  const fontsStylesheets = allFontsLinks.filter((m) =>
+    /\brel\s*=\s*["']stylesheet["']/i.test(m[0])
+  )
+  fontsStylesheets.forEach((m, i) => {
+    const href = /\bhref\s*=\s*["']([^"']+)["']/i.exec(m[0])
+    if (href && !/display=swap/i.test(href[1])) {
+      errors.push({
+        rule: 'fonts-missing-display-swap',
+        message: `Google Fonts stylesheet #${i + 1} is missing display=swap. Add &display=swap to the URL.`,
+        snippet: href[1].slice(0, 120),
+      })
+    }
+  })
+
+  // 7. If Google Fonts stylesheet present, preconnect for fonts.gstatic.com should also be present.
+  if (fontsStylesheets.length > 0) {
+    const hasGstaticPreconnect = /<link\b[^>]*rel\s*=\s*["']preconnect["'][^>]*fonts\.gstatic\.com/i.test(html)
+    if (!hasGstaticPreconnect) {
+      warnings.push({
+        rule: 'fonts-missing-gstatic-preconnect',
+        message: 'Google Fonts stylesheet present but no <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>.',
+      })
+    }
+  }
+
+  // 8. If multiple images, most should have loading attribute. Warn when most are missing.
+  if (imgs.length >= 2) {
+    const withoutLoading = imgs.filter((m) => !/\bloading\s*=/i.test(m[0])).length
+    if (withoutLoading >= imgs.length - 1) {
+      // -1 leaves room for the LCP image which should be loading="eager" or have no attr
+      warnings.push({
+        rule: 'imgs-missing-loading',
+        message: `${withoutLoading}/${imgs.length} <img> tags lack a loading attribute. The hero/LCP can be eager; the rest should be lazy.`,
+      })
+    }
+  }
+
+  // 9. If any image is in the markup, the hero should have a preload link (heuristic).
+  if (imgs.length > 0) {
+    const hasPreload = /<link\b[^>]*rel\s*=\s*["']preload["'][^>]*as\s*=\s*["']image["']/i.test(html) ||
+      /<link\b[^>]*as\s*=\s*["']image["'][^>]*rel\s*=\s*["']preload["']/i.test(html)
+    if (!hasPreload) {
+      warnings.push({
+        rule: 'no-hero-preload',
+        message: 'No <link rel="preload" as="image"> found. The hero image should be preloaded for LCP.',
+      })
+    }
+  }
+
+  // 10. Defensive specificity heuristic: count selectors with the scope class repeated as ancestor.
+  // We can't know the scope name from the HTML alone, but we can check for the pattern
+  // ".something .something__" which is a strong signal of correct chaining.
+  if (css.length > 0) {
+    const chainedSelectors = findAll(/\.([a-z][a-z0-9_-]*)\s+\.\1__/gi, css).length
+    info.push({
+      rule: 'defensive-specificity-count',
+      message: `Found ${chainedSelectors} selector(s) using the chained-scope pattern (.scope .scope__X). More is better.`,
+    })
+    if (chainedSelectors === 0 && css.length > 200) {
+      warnings.push({
+        rule: 'no-defensive-specificity',
+        message: 'No selectors found using the chained-scope pattern (.scope .scope__X). Anti-pattern #5b: theme overrides will win.',
+      })
+    }
+  }
+
+  // 11. Reset rule heuristic.
+  if (css.length > 0 && !/box-sizing\s*:\s*border-box/i.test(css)) {
+    warnings.push({
+      rule: 'no-reset-box-sizing',
+      message: 'No box-sizing: border-box reset found. Add the universal reset to the top of the <style> block.',
+    })
+  }
+
+  return {
+    passed: errors.length === 0,
+    errorCount: errors.length,
+    warningCount: warnings.length,
+    errors,
+    warnings,
+    info,
+  }
+}
+
+// --- prettier (lazy, optional) ------------------------------------------------
+
+async function tryPrettierFormat(html, verbose) {
+  let prettier
+  try {
+    prettier = await import('prettier')
+  } catch {
+    log(verbose, 'prettier not installed — writing unformatted')
+    return { html, formatted: false, reason: 'prettier-not-installed' }
+  }
+  try {
+    const out = await prettier.format(html, {
+      parser: 'html',
+      printWidth: 100,
+      tabWidth: 2,
+      htmlWhitespaceSensitivity: 'css',
+    })
+    return { html: out, formatted: true, reason: null }
+  } catch (err) {
+    log(verbose, `prettier failed: ${err.message} — writing unformatted`)
+    return { html, formatted: false, reason: `prettier-error: ${err.message}` }
+  }
+}
+
+// --- entry --------------------------------------------------------------------
+
+const argv = process.argv.slice(2)
+
+if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+  process.stdout.write(HELP)
+  process.exit(0)
+}
+
+const subcommand = argv[0]
+const rest = argv.slice(1)
+
+if (subcommand !== 'validate' && subcommand !== 'write') {
+  fail(`unknown subcommand '${subcommand}' — use 'validate' or 'write'`)
+}
+
+const { values } = parseArgs({
+  args: rest,
+  options: {
+    'html-file': { type: 'string' },
+    'output-path': { type: 'string' },
+    verbose: { type: 'boolean', default: false },
+    help: { type: 'boolean', default: false },
+  },
+  strict: false,
+})
+
+if (values.help) {
+  process.stdout.write(HELP)
+  process.exit(0)
+}
+
+async function main() {
+  if (subcommand === 'validate') {
+    if (!values['html-file']) fail('validate: missing --html-file')
+    const path = resolve(values['html-file'])
+    let html
+    try {
+      html = await readFile(path, 'utf8')
+    } catch (err) {
+      fail(`validate: cannot read ${path}: ${err.message}`, 1)
+    }
+    log(values.verbose, `validating ${path} (${html.length} bytes)`)
+    const report = validateHtml(html)
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+    process.exit(report.passed ? 0 : 3)
+  }
+
+  if (subcommand === 'write') {
+    if (!values['output-path']) fail('write: missing --output-path')
+    const out = resolve(values['output-path'])
+    let html
+    try {
+      html = await readStdin()
+    } catch (err) {
+      fail(`write: failed to read stdin: ${err.message}`, 1)
+    }
+    if (!html.trim()) fail('write: stdin was empty', 2)
+    log(values.verbose, `read ${html.length} bytes from stdin`)
+    const fmt = await tryPrettierFormat(html, values.verbose)
+    try {
+      await mkdir(dirname(out), { recursive: true })
+      await writeFile(out, fmt.html, 'utf8')
+    } catch (err) {
+      fail(`write: failed to write ${out}: ${err.message}`, 1)
+    }
+    const payload = JSON.stringify(
+      {
+        path: out,
+        bytes: Buffer.byteLength(fmt.html, 'utf8'),
+        formatted: fmt.formatted,
+        formatterSkippedReason: fmt.reason,
+      },
+      null,
+      2,
+    )
+    process.stdout.write(`${payload}\n`)
+    process.exit(0)
+  }
+}
+
+main().catch((err) => fail(`unhandled: ${err.stack || err.message}`, 1))

package/templates/skills/sb-build-wp/scripts/tests/test-build-wp.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+// test-build-wp.mjs — Smoke tests for build-wp.mjs.
+// Validates: --help works, missing args fail with exit 2, validate catches the
+// canonical anti-patterns (exit 3), validate passes a clean fragment (exit 0),
+// write persists to the requested path. No prettier dependency required for
+// tests to pass.
+
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve, join } from 'node:path'
+import { mkdirSync, writeFileSync, readFileSync, rmSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { strict as assert } from 'node:assert'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const SCRIPT = resolve(here, '..', 'build-wp.mjs')
+const TMP = join(tmpdir(), `sb-build-wp-test-${process.pid}`)
+
+mkdirSync(TMP, { recursive: true })
+
+let passed = 0
+let failed = 0
+
+function test(name, fn) {
+  try {
+    fn()
+    process.stdout.write(`ok - ${name}\n`)
+    passed++
+  } catch (err) {
+    process.stdout.write(`not ok - ${name}\n  ${err.message}\n`)
+    failed++
+  }
+}
+
+function run(args, input) {
+  return spawnSync('node', [SCRIPT, ...args], {
+    encoding: 'utf8',
+    input: input ?? undefined,
+  })
+}
+
+function writeTmp(name, content) {
+  const p = join(TMP, name)
+  writeFileSync(p, content)
+  return p
+}
+
+const CLEAN_HTML = `
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link rel="preload" as="image" href="/assets/abc123.jpg">
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap">
+<style>
+  .hero, .hero * { box-sizing: border-box; margin: 0; padding: 0; }
+  .hero { width: 100vw; margin-left: calc(50% - 50vw); }
+  .hero .hero__title { font-size: 32px !important; font-weight: 700 !important; }
+  .hero .hero__media { aspect-ratio: 1 / 1.3; max-height: 700px; }
+  @media (min-width: 1000px) {
+    .hero .hero__media { aspect-ratio: 16 / 9; }
+  }
+</style>
+<section class="hero">
+  <img src="/assets/abc123.jpg" alt="Brand hero" loading="eager">
+  <h1 class="hero__title">Welcome</h1>
+  <button type="button" class="hero__cta" aria-label="Shop now">Shop</button>
+  <img src="/assets/def456.jpg" alt="" loading="lazy">
+</section>
+`
+
+// ---- Help and arg validation ----
+
+test('--help exits 0 and prints usage', () => {
+  const r = run(['--help'])
+  assert.equal(r.status, 0, `exit code was ${r.status}`)
+  assert.match(r.stdout, /build-wp\.mjs/)
+  assert.match(r.stdout, /validate/)
+  assert.match(r.stdout, /write/)
+})
+
+test('no args exits 0 and shows help', () => {
+  const r = run([])
+  assert.equal(r.status, 0)
+  assert.match(r.stdout, /Subcommands/)
+})
+
+test('unknown subcommand exits 2', () => {
+  const r = run(['frobnicate'])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /unknown subcommand/)
+})
+
+test('validate without --html-file exits 2', () => {
+  const r = run(['validate'])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /missing --html-file/)
+})
+
+test('write without --output-path exits 2', () => {
+  const r = run(['write'], '<style></style>')
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /missing --output-path/)
+})
+
+test('write with empty stdin exits 2', () => {
+  const r = run(['write', '--output-path', join(TMP, 'never.html')], '')
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /stdin was empty/)
+})
+
+// ---- Validation: clean fragment passes ----
+
+test('validate: clean fragment passes (exit 0)', () => {
+  const p = writeTmp('clean.html', CLEAN_HTML)
+  const r = run(['validate', '--html-file', p])
+  assert.equal(r.status, 0, `stderr: ${r.stderr}\nstdout: ${r.stdout}`)
+  const report = JSON.parse(r.stdout)
+  assert.equal(report.passed, true)
+  assert.equal(report.errorCount, 0)
+})
+
+// ---- Validation: each rule trips when violated ----
+
+test('validate: missing <style> reports error', () => {
+  const p = writeTmp('no-style.html', '<section><h1>hi</h1></section>')
+  const r = run(['validate', '--html-file', p])
+  assert.equal(r.status, 3)
+  const report = JSON.parse(r.stdout)
+  assert.ok(report.errors.find((e) => e.rule === 'missing-style-block'))
+})
+
+test('validate: <img> without alt reports error', () => {
+  const html = CLEAN_HTML.replace('<img src="/assets/abc123.jpg" alt="Brand hero" loading="eager">', '<img src="/assets/abc123.jpg" loading="eager">')
+  const p = writeTmp('no-alt.html', html)
+  const r = run(['validate', '--html-file', p])
+  assert.equal(r.status, 3)
+  const report = JSON.parse(r.stdout)
+  assert.ok(report.errors.find((e) => e.rule === 'img-missing-alt'))
+})
+
+test('validate: <button> without type reports error', () => {
+  const html = CLEAN_HTML.replace('<button type="button" class="hero__cta" aria-label="Shop now">Shop</button>', '<button class="hero__cta" aria-label="Shop now">Shop</button>')
+  const p = writeTmp('no-type.html', html)
+  const r = run(['validate', '--html-file', p])
+  assert.equal(r.status, 3)
+  const report = JSON.parse(r.stdout)
+  assert.ok(report.errors.find((e) => e.rule === 'button-missing-type'))
+})
+
+test('validate: data:image/svg+xml in img src reports error', () => {
+  const html = CLEAN_HTML.replace(
+    '<img src="/assets/abc123.jpg" alt="Brand hero" loading="eager">',
+    '<img src="data:image/svg+xml,%3Csvg%3E%3C/svg%3E" alt="Brand hero" loading="eager">'
+  )
+  const p = writeTmp('fake-svg.html', html)
+  const r = run(['validate', '--html-file', p])
+  assert.equal(r.status, 3)
+  const report = JSON.parse(r.stdout)
+  assert.ok(report.errors.find((e) => e.rule === 'fabricated-svg-data-uri'))
+})
+
+test('validate: 100vh on height reports error', () => {
+  const html = CLEAN_HTML.replace('aspect-ratio: 1 / 1.3; max-height: 700px;', 'height: 100vh;')
+  const p = writeTmp('vh.html', html)
+  const r = run(['validate', '--html-file', p])
+  assert.equal(r.status, 3)
+  const report = JSON.parse(r.stdout)
+  assert.ok(report.errors.find((e) => e.rule === 'hero-100vh'))
+})
+
+test('validate: Google Fonts without display=swap reports error', () => {
+  const html = CLEAN_HTML.replace('&display=swap', '')
+  const p = writeTmp('no-swap.html', html)
+  const r = run(['validate', '--html-file', p])
+  assert.equal(r.status, 3)
+  const report = JSON.parse(r.stdout)
+  assert.ok(report.errors.find((e) => e.rule === 'fonts-missing-display-swap'))
+})
+
+test('validate: missing reset emits warning (not error)', () => {
+  const html = `<style>.x .x__y { color: red; }</style><section class="x"><span class="x__y">hi</span></section>`
+  const p = writeTmp('no-reset.html', html)
+  const r = run(['validate', '--html-file', p])
+  // No errors → exit 0 even with warnings.
+  assert.equal(r.status, 0)
+  const report = JSON.parse(r.stdout)
+  assert.ok(report.warnings.find((w) => w.rule === 'no-reset-box-sizing'))
+})
+
+// ---- write subcommand ----
+
+test('write: persists stdin to output path', () => {
+  const out = join(TMP, 'nested', 'out.html')
+  const html = '<style>.x{color:red}</style><div class="x">hi</div>'
+  const r = run(['write', '--output-path', out], html)
+  assert.equal(r.status, 0, `stderr: ${r.stderr}`)
+  const report = JSON.parse(r.stdout)
+  assert.equal(report.path, out)
+  assert.ok(report.bytes > 0)
+  assert.ok(existsSync(out))
+  const content = readFileSync(out, 'utf8')
+  // prettier may or may not be installed — the content must at least include the input
+  assert.match(content, /<style>/)
+  assert.match(content, /\.x/)
+})
+
+test('write: creates parent directories', () => {
+  const out = join(TMP, 'a', 'b', 'c', 'deep.html')
+  const r = run(['write', '--output-path', out], '<p>x</p>')
+  assert.equal(r.status, 0)
+  assert.ok(existsSync(out))
+})
+
+// ---- Cleanup ----
+
+try {
+  rmSync(TMP, { recursive: true, force: true })
+} catch {}
+
+if (failed > 0) {
+  process.stdout.write(`\n${failed} failed, ${passed} passed\n`)
+  process.exit(1)
+}
+process.stdout.write(`\n${passed} passed\n`)
+process.exit(0)

package/templates/skills/sb-compare-visual/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: sb-compare-visual
+description: Compares the live-page screenshot against the build screenshot pixel-by-pixel and (optionally) cross-checks measured tokens, returning a prioritized list of structured diffs and a red-overlay diff map. Use when the SimilarBuild orchestrator (`/build-page`, `/build-site`, `/clip-section`) requests visual comparison after `sb-validate-render`, or when the user asks to 'compare visual' between a live page and a build.
+---
+
+# sb-compare-visual
+
+## Overview
+
+Closes the **validate → compare** loop. Takes the screenshot `sb-validate-render` produced (the build, rendered with the destination's theme reset injected) and the live-page screenshot `sb-inspect-live` captured, normalizes their canvas with sharp, runs pixelmatch over the pair, and writes a red-overlay diff map. When the optional `--tokens-live` and `--tokens-build` JSON files are passed, it additionally cross-checks the measured tokens (h1/h2/h3 size + color, body typography, button geometry, container width, viewport overflow) and emits a prioritized list of structured diffs that the orchestrator feeds to `sb-review-checks` for fix candidates.
+
+Pure determinism — no browser, no network. The script does the work; this SKILL.md only describes inputs, outputs, and how to react to a non-zero exit.
+
+This skill **only reports differences**. Generating fix suggestions is `sb-review-checks`'s job. Keep that separation: a clean diff list now means a clean fix list later.
+
+## Inputs
+
+| Argument             | Required | Default | Notes                                                                       |
+| -------------------- | -------- | ------- | --------------------------------------------------------------------------- |
+| `live-screenshot`    | yes      | —       | PNG from `sb-inspect-live`.                                                 |
+| `build-screenshot`   | yes      | —       | PNG from `sb-validate-render` (`{render-output-dir}/screenshot.png`).       |
+| `output-dir`         | yes      | —       | Directory for `diff-map.png` + `report.json`.                               |
+| `tokens-live`        | no       | —       | JSON from `sb-inspect-live` (provides `tokens`/`geometry`).                 |
+| `tokens-build`       | no       | —       | `render.json` from `sb-validate-render`.                                    |
+| `threshold`          | no       | `10`    | Pass threshold for `diffPercent`. Comes from config `diff_threshold_percent`. Raised from 5 (Pattern #22 + smoke): pixelmatch is severe on font/anti-aliasing drift even when visual fidelity is good. |
+| `pixel-threshold`    | no       | `0.2`   | pixelmatch per-pixel sensitivity (0=strict, 1=permissive). Raised from 0.1 (Pattern #22 + smoke): 0.1 flagged identical-color screenshots with sub-pixel font shifts as 80%+ different. |
+| `crop-live-bbox`     | no       | —       | `x,y,w,h` in CSS pixels. When the build is a single section but the live screenshot is full-page, pass `inspection.sectionBoundingBox` here so the live is cropped before diffing (anti-pattern #10). |
+| `crop-live-dpr`      | no       | `3`     | DPR multiplier for `--crop-live-bbox`. `sb-inspect-live` captures with the iPhone 14 device profile (`deviceScaleFactor=3`), so screenshot pixels = CSS pixels × 3. Override only if the inspector ran with a different profile. |
+| `crop-build-bbox`    | no       | —       | `x,y,w,h` in CSS pixels. Symmetric of `--crop-live-bbox` (Pattern #27): when the build is a section shorter than the captured viewport, sb-validate-render's screenshot has dead viewport space below the content. Pass `render.geometry.sections[0].bbox` (or `probeRoot.bbox`) here to crop before diffing. Skip when `render.geometry.viewportOverflow === true` (bbox would underestimate). |
+| `crop-build-dpr`     | no       | `3`     | DPR multiplier for `--crop-build-bbox`. `sb-validate-render` runs with `deviceScaleFactor=3` (Pattern #22 alignment), so screenshot pixels = CSS pixels × 3. Override only if validate-render ran at a different DPR. |
+
+Pass both `--tokens-live` and `--tokens-build` together — passing one without the other silently skips the token diff (the comparison only makes sense with both sides).
+
+## Output
+
+A single JSON object printed to stdout AND saved to `{output-dir}/report.json`:
+
+```json
+{
+  "passed": false,
+  "diffPercent": 6.42,
+  "diffPixels": 50124,
+  "totalPixels": 780480,
+  "threshold": 5,
+  "pixelThreshold": 0.1,
+  "diffMap": "{output-dir}/diff-map.png",
+  "report": "{output-dir}/report.json",
+  "dimensions": {
+    "live":   { "width": 780, "height": 2014 },
+    "build":  { "width": 780, "height": 1972 },
+    "canvas": { "width": 780, "height": 2014 }
+  },
+  "tokenDiff": { "compared": true, "count": 3 },
+  "structuredDiffs": [
+    { "area": "h1", "issue": "font-size 24px vs 27px expected", "severity": "high", "live": "27px", "build": "24px", "deltaPx": -3 },
+    { "area": "button", "issue": "background-color #d8112a vs #d82a11 expected", "severity": "high", "live": "#d82a11", "build": "#d8112a" },
+    { "area": "button", "issue": "button height 44px vs 40px expected", "severity": "medium", "live": 40, "build": 44, "deltaPx": 4 }
+  ],
+  "croppedLiveTo": null,
+  "croppedBuildTo": null,
+  "inputs": { "liveScreenshot": "...", "buildScreenshot": "...", "tokensLive": "...", "tokensBuild": "..." }
+}
+```
+
+When `--crop-live-bbox` was passed, `croppedLiveTo` carries the bbox echo + screenshot-pixel resolution + the path of the cropped live PNG (also written to `{output-dir}/live-cropped.png` for debug). When omitted, it's `null`. `croppedBuildTo` mirrors this for `--crop-build-bbox` (debug PNG: `{output-dir}/build-cropped.png`).
+
+`structuredDiffs` is sorted **high → medium → low** so the orchestrator's first slice is always the most urgent. `diff-map.png` is written even when `passed: true` — useful for spot-checking close calls.
+
+## Dependencies
+
+The host project must have `sharp`, `pixelmatch`, and `pngjs` installed (the SimilarBuild installer handles all three; sharp is already a dep of `sb-extract-assets`, pixelmatch + pngjs are new). Node ≥ 20.
+
+## On Activation
+
+1. **Resolve inputs.** Collect `live-screenshot`, `build-screenshot`, `output-dir`. Optional: `tokens-live`, `tokens-build`, `threshold`, `pixel-threshold`. Pass through `diff_threshold_percent` from `.claude/sb-config.yaml` if available; otherwise the script's default of 5% applies.
+
+2. **Ensure `output-dir` exists.** `mkdir -p` it.
+
+3. **Run the script.** From the project root:
+
+   ```bash
+   node {skill-root}/scripts/compare-visual.mjs \
+     --live-screenshot "{live-png}" \
+     --build-screenshot "{build-png}" \
+     --output-dir "{output-dir}" \
+     [--tokens-live "{inspection.json}"] \
+     [--tokens-build "{render.json}"] \
+     [--threshold 10] \
+     [--pixel-threshold 0.2] \
+     [--crop-live-bbox "{x,y,w,h}"] \
+     [--crop-live-dpr 3] \
+     [--crop-build-bbox "{x,y,w,h}"] \
+     [--crop-build-dpr 3]
+   ```
+
+   The script handles: dimension probe, transparent-pad to the union canvas (NOT resize — resize distorts and triggers false positives), PNG decode via pngjs, pixelmatch, red-overlay diff PNG, and the token cross-check. See `scripts/compare-visual.mjs --help` for the full flag list.
+
+4. **Branch on exit code.**
+   - `0` — `passed: true`, ship it.
+   - `3` — `passed: false`, comparison failed. **Not a script error.** Parse the JSON anyway; `structuredDiffs` is the input to `sb-review-checks` and the next re-roll of `sb-build-{wp,shopify}` (via its `fixHints`).
+   - `1` — actual script error. Surface stderr to the user and stop.
+   - `2` — invalid args. Fix the call.
+
+5. **Forward the JSON unchanged** to the caller. Do not summarize, mutate, or strip fields. Downstream consumers (the orchestrator's auto-correct loop, `sb-review-checks`, the HTML report) read every field directly.
+
+## Failure modes
+
+| Symptom                                            | Likely cause                                                    | What to surface                                                                       |
+| -------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| Exit 1, stderr mentions `sharp`/`pixelmatch`/`pngjs` | Dependency not installed                                       | Pass stderr verbatim. Suggest `npm i sharp pixelmatch pngjs`.                         |
+| Exit 1, "could not read dimensions"                | Input PNG is corrupt / 0 bytes (often: `sb-validate-render`'s `warnings[]` flagged a tiny screenshot upstream) | Pass stderr verbatim. The build screenshot is unusable — re-roll `sb-validate-render` first. |
+| Exit 3 with `diffPercent > 50`                     | Massive layout drift OR build screenshot shows the wrong section | Look at `diff-map.png` first. If the entire image is red, the build is structurally wrong, not visually drifted — escalate to `sb-build-{wp,shopify}` re-roll, not `sb-review-checks`. |
+| `tokenDiff.compared: false`, `reason: tokens-unreadable` | One of the JSON files is malformed                       | Inspect the source skill's output. Pixel diff is still valid; token diff is just absent. |
+| `structuredDiffs[].severity: 'high'` for all entries | Wholly different theme — fonts, colors, geometry all drifted   | Likely missing or wrong preset YAML in `sb-validate-render` — its theme reset isn't matching the destination. |
+
+## Conventions
+
+- Bare paths (e.g. `scripts/compare-visual.mjs`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory.
+- `{project-root}` resolves to the project working directory.
+- Sizes are normalized by **transparent padding to the union canvas**, never by resizing. Resizing distorts pixel positions and produces a sea of red pixels even on near-identical inputs; padding only flags areas where one side has content the other lacks (which is exactly what we want to know).