similarbuild 0.1.0

package/templates/skills/sb-compare-visual/scripts/compare-visual.mjs

@@ -0,0 +1,387 @@
+#!/usr/bin/env node
+// compare-visual.mjs — Compare a live-page screenshot against a build screenshot
+// pixel-by-pixel and (optionally) cross-check measured tokens. Returns a
+// prioritized list of structured differences plus a red-overlay diff map.
+//
+// Pure determinism: pixelmatch + sharp + numeric comparison. No browser, no
+// network. Lazy-imports sharp/pixelmatch/pngjs so --help and arg validation
+// work without the deps installed.
+//
+// Outputs JSON to stdout AND writes diff-map.png + report.json into --output-dir.
+// Exit codes: 0=passed, 1=script error, 2=invalid args, 3=comparison failed
+// (diffPercent > threshold). Exit 3 lets the orchestrator branch on "needs
+// re-roll vs ready to ship" without parsing JSON, while still surfacing the
+// full report to the user / next stage.
+
+import { parseArgs } from 'node:util'
+import { mkdir, writeFile, readFile, access } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { compareTokens, compareGeometryBlocks, sortBySeverity } from './lib/compare-tokens.mjs'
+
+const HELP = `
+compare-visual.mjs — Diff a live screenshot vs a build screenshot + token cross-check.
+
+Required:
+  --live-screenshot <path>   PNG from sb-inspect-live.
+  --build-screenshot <path>  PNG from sb-validate-render.
+  --output-dir <dir>         Directory for diff-map.png + report.json.
+
+Optional:
+  --tokens-live <path>       JSON from sb-inspect-live (tokens block) for token diff.
+  --tokens-build <path>      JSON from sb-validate-render (render.json) for token diff.
+  --threshold <percent>      Pass threshold for diffPercent. Default 10.
+  --pixel-threshold <0..1>   Per-pixel matching strictness for pixelmatch. Default 0.2.
+  --crop-live-bbox <x,y,w,h> Crop the live screenshot to this CSS-pixel bbox before
+                             diffing. Pair with sectionBoundingBox from
+                             sb-inspect-live to align scope (anti-pattern #10).
+  --crop-live-dpr <n>        DPR multiplier for --crop-live-bbox (CSS px → screenshot px).
+                             Default 3 (matches sb-inspect-live's iPhone 14 profile).
+  --crop-build-bbox <x,y,w,h> Crop the build screenshot to this CSS-pixel bbox before
+                             diffing. Pair with render.geometry.sections[0].bbox (or
+                             probeRoot) from sb-validate-render — eliminates dead
+                             viewport space below short sections (Pattern #27,
+                             symmetric of anti-pattern #10).
+  --crop-build-dpr <n>       DPR multiplier for --crop-build-bbox. Default 3 (matches
+                             sb-validate-render's deviceScaleFactor=3 alignment).
+  --help                     Show this message.
+
+Exit codes: 0=passed, 1=script error, 2=invalid args, 3=comparison failed.
+`
+
+function fail(msg, code = 2) {
+  process.stderr.write(`[sb-compare-visual] ${msg}\n`)
+  process.exit(code)
+}
+
+function log(msg) {
+  process.stderr.write(`[sb-compare-visual] ${msg}\n`)
+}
+
+const { values } = parseArgs({
+  options: {
+    'live-screenshot': { type: 'string' },
+    'build-screenshot': { type: 'string' },
+    'tokens-live': { type: 'string' },
+    'tokens-build': { type: 'string' },
+    'output-dir': { type: 'string' },
+    threshold: { type: 'string', default: '10' },
+    'pixel-threshold': { type: 'string', default: '0.2' },
+    'crop-live-bbox': { type: 'string' },
+    'crop-live-dpr': { type: 'string', default: '3' },
+    'crop-build-bbox': { type: 'string' },
+    'crop-build-dpr': { type: 'string', default: '3' },
+    help: { type: 'boolean', default: false },
+  },
+  strict: false,
+})
+
+if (values.help) {
+  process.stdout.write(HELP)
+  process.exit(0)
+}
+
+if (!values['live-screenshot']) fail('missing --live-screenshot')
+if (!values['build-screenshot']) fail('missing --build-screenshot')
+if (!values['output-dir']) fail('missing --output-dir')
+
+const LIVE = resolve(values['live-screenshot'])
+const BUILD = resolve(values['build-screenshot'])
+const OUTPUT_DIR = resolve(values['output-dir'])
+const TOKENS_LIVE = values['tokens-live'] ? resolve(values['tokens-live']) : null
+const TOKENS_BUILD = values['tokens-build'] ? resolve(values['tokens-build']) : null
+const THRESHOLD = parseFloat(values.threshold)
+const PIXEL_THRESHOLD = parseFloat(values['pixel-threshold'])
+
+if (!Number.isFinite(THRESHOLD) || THRESHOLD < 0 || THRESHOLD > 100) {
+  fail('--threshold must be a number between 0 and 100')
+}
+if (!Number.isFinite(PIXEL_THRESHOLD) || PIXEL_THRESHOLD < 0 || PIXEL_THRESHOLD > 1) {
+  fail('--pixel-threshold must be a number between 0 and 1')
+}
+
+// Crop bbox parsing. Format: "x,y,w,h" in CSS pixels. Multiplied by the matching
+// --*-dpr flag (default 3) to convert to screenshot pixels — both sb-inspect-live
+// (iPhone 14 device profile) and sb-validate-render (deviceScaleFactor=3 alignment,
+// Pattern #22) capture at DPR 3, so bbox values from upstream JSON are in CSS px.
+function parseBboxFlag(raw, flagName) {
+  if (!raw) return null
+  const parts = raw.split(',').map((s) => parseFloat(s.trim()))
+  if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) {
+    fail(`${flagName} must be four comma-separated numbers (x,y,w,h)`)
+  }
+  const [x, y, w, h] = parts
+  if (w <= 0 || h <= 0) fail(`${flagName} width and height must be positive`)
+  if (x < 0 || y < 0) fail(`${flagName} x and y must be ≥ 0`)
+  return { x, y, w, h }
+}
+function parseDprFlag(raw, flagName) {
+  const dpr = parseFloat(raw)
+  if (!Number.isFinite(dpr) || dpr <= 0) fail(`${flagName} must be a positive number`)
+  return dpr
+}
+const CROP_BBOX = parseBboxFlag(values['crop-live-bbox'], '--crop-live-bbox')
+const CROP_DPR = parseDprFlag(values['crop-live-dpr'], '--crop-live-dpr')
+const CROP_BUILD_BBOX = parseBboxFlag(values['crop-build-bbox'], '--crop-build-bbox')
+const CROP_BUILD_DPR = parseDprFlag(values['crop-build-dpr'], '--crop-build-dpr')
+
+async function ensureExists(path, label) {
+  try {
+    await access(path)
+  } catch {
+    fail(`${label} not found: ${path}`)
+  }
+}
+
+// Pad a PNG buffer (decoded as { data, width, height }) to target dims by
+// extending right + bottom with transparent pixels. Padding (not resizing) is
+// the right call: resizing distorts pixel positions and would trigger massive
+// false positives across the whole image. Padding only flags areas where one
+// side has content that the other lacks — which is exactly what we want.
+async function padToDims(sharp, buffer, targetW, targetH) {
+  const meta = await sharp(buffer).metadata()
+  const padRight = Math.max(0, targetW - meta.width)
+  const padBottom = Math.max(0, targetH - meta.height)
+  if (padRight === 0 && padBottom === 0) return buffer
+  return sharp(buffer)
+    .extend({
+      top: 0,
+      left: 0,
+      right: padRight,
+      bottom: padBottom,
+      background: { r: 0, g: 0, b: 0, alpha: 0 },
+    })
+    .png()
+    .toBuffer()
+}
+
+async function loadJsonIfPresent(path) {
+  if (!path) return null
+  try {
+    const raw = await readFile(path, 'utf8')
+    return JSON.parse(raw)
+  } catch (err) {
+    log(`could not read tokens file ${path}: ${err.message} — skipping token diff`)
+    return null
+  }
+}
+
+async function main() {
+  await ensureExists(LIVE, '--live-screenshot')
+  await ensureExists(BUILD, '--build-screenshot')
+  await mkdir(OUTPUT_DIR, { recursive: true })
+
+  const diffMapPath = join(OUTPUT_DIR, 'diff-map.png')
+  const reportPath = join(OUTPUT_DIR, 'report.json')
+
+  let sharp, pixelmatch, PNG
+  try {
+    sharp = (await import('sharp')).default
+  } catch (err) {
+    process.stderr.write(
+      `[sb-compare-visual] missing dependency 'sharp': ${err?.message || err}\n` +
+        `Install with: npm i sharp\n`,
+    )
+    process.exit(1)
+  }
+  try {
+    const mod = await import('pixelmatch')
+    pixelmatch = mod.default || mod
+  } catch (err) {
+    process.stderr.write(
+      `[sb-compare-visual] missing dependency 'pixelmatch': ${err?.message || err}\n` +
+        `Install with: npm i pixelmatch\n`,
+    )
+    process.exit(1)
+  }
+  try {
+    ;({ PNG } = await import('pngjs'))
+  } catch (err) {
+    process.stderr.write(
+      `[sb-compare-visual] missing dependency 'pngjs': ${err?.message || err}\n` +
+        `Install with: npm i pngjs\n`,
+    )
+    process.exit(1)
+  }
+
+  log(`reading live=${LIVE}`)
+  log(`reading build=${BUILD}`)
+  const [liveRawOriginal, buildRawOriginal] = await Promise.all([readFile(LIVE), readFile(BUILD)])
+
+  // Crop helper. Used for both live (anti-pattern #10) and build (Pattern #27,
+  // symmetric of #10): sb-validate-render captures the full mobile viewport
+  // (390×844 CSS) but a single-section build often only fills part of it. The
+  // empty viewport space below the section pads against any cropped live and
+  // inflates diff% with "build has white space, live doesn't" pixels — same
+  // failure mode as #10, just on the other side. Cropping both sides to their
+  // measured bboxes aligns scope symmetrically.
+  async function applyCrop(buffer, bbox, dpr, label, debugFilename) {
+    const meta = await sharp(buffer).metadata()
+    const ow = meta.width || 0
+    const oh = meta.height || 0
+    const left = Math.max(0, Math.round(bbox.x * dpr))
+    const top = Math.max(0, Math.round(bbox.y * dpr))
+    let width = Math.round(bbox.w * dpr)
+    let height = Math.round(bbox.h * dpr)
+    // Clamp to fit. Sections can extend off-screen via sticky/clip-path edge
+    // cases — clamping keeps the comparison alive instead of bailing.
+    if (left + width > ow) width = Math.max(1, ow - left)
+    if (top + height > oh) height = Math.max(1, oh - top)
+    if (left >= ow || top >= oh || width <= 0 || height <= 0) {
+      fail(
+        `${label} is entirely outside the screenshot ` +
+          `(bbox=${bbox.x},${bbox.y},${bbox.w},${bbox.h} dpr=${dpr} src=${ow}x${oh})`,
+        1,
+      )
+    }
+    log(
+      `cropping ${label.replace('--crop-', '').replace('-bbox', '')}: ` +
+        `bbox=${bbox.x},${bbox.y},${bbox.w},${bbox.h} dpr=${dpr} → ` +
+        `screenshot-px ${left},${top},${width}x${height} (orig ${ow}x${oh})`,
+    )
+    const croppedBuffer = await sharp(buffer).extract({ left, top, width, height }).png().toBuffer()
+    const debugPath = join(OUTPUT_DIR, debugFilename)
+    await writeFile(debugPath, croppedBuffer)
+    return {
+      buffer: croppedBuffer,
+      record: {
+        x: bbox.x,
+        y: bbox.y,
+        w: bbox.w,
+        h: bbox.h,
+        dpr,
+        screenshotPx: { left, top, width, height },
+        path: debugPath,
+      },
+    }
+  }
+
+  let liveRaw = liveRawOriginal
+  let croppedLiveTo = null
+  if (CROP_BBOX) {
+    const r = await applyCrop(liveRawOriginal, CROP_BBOX, CROP_DPR, '--crop-live-bbox', 'live-cropped.png')
+    liveRaw = r.buffer
+    croppedLiveTo = r.record
+  }
+
+  let buildRaw = buildRawOriginal
+  let croppedBuildTo = null
+  if (CROP_BUILD_BBOX) {
+    const r = await applyCrop(buildRawOriginal, CROP_BUILD_BBOX, CROP_BUILD_DPR, '--crop-build-bbox', 'build-cropped.png')
+    buildRaw = r.buffer
+    croppedBuildTo = r.record
+  }
+
+  // Probe dimensions to compute the union canvas. Pad both inputs to the union
+  // size so pixelmatch sees identically-sized images.
+  const [liveMeta, buildMeta] = await Promise.all([
+    sharp(liveRaw).metadata(),
+    sharp(buildRaw).metadata(),
+  ])
+  const targetW = Math.max(liveMeta.width || 0, buildMeta.width || 0)
+  const targetH = Math.max(liveMeta.height || 0, buildMeta.height || 0)
+
+  if (!targetW || !targetH) {
+    fail(`could not read dimensions from one of the screenshots (live=${liveMeta.width}x${liveMeta.height}, build=${buildMeta.width}x${buildMeta.height})`, 1)
+  }
+
+  log(`canvas ${targetW}x${targetH} (live ${liveMeta.width}x${liveMeta.height}, build ${buildMeta.width}x${buildMeta.height})`)
+
+  // Pad as needed, then re-encode to PNG so pngjs can decode the raw RGBA buffer
+  // pixelmatch needs.
+  const [livePadded, buildPadded] = await Promise.all([
+    padToDims(sharp, liveRaw, targetW, targetH),
+    padToDims(sharp, buildRaw, targetW, targetH),
+  ])
+
+  // sharp → raw RGBA via PNG re-encode + pngjs decode. We could go straight from
+  // sharp.raw() but pixelmatch expects 4-channel RGBA at the same byte layout
+  // pngjs produces, so stay on the PNG path for fewer surprises.
+  const livePng = PNG.sync.read(livePadded)
+  const buildPng = PNG.sync.read(buildPadded)
+  const diffPng = new PNG({ width: targetW, height: targetH })
+
+  log(`pixelmatch threshold=${PIXEL_THRESHOLD}`)
+  const diffPixels = pixelmatch(
+    livePng.data,
+    buildPng.data,
+    diffPng.data,
+    targetW,
+    targetH,
+    {
+      threshold: PIXEL_THRESHOLD,
+      includeAA: false,
+      alpha: 0.2,
+      diffColor: [255, 0, 0],
+      diffColorAlt: [255, 64, 0],
+    },
+  )
+  const totalPixels = targetW * targetH
+  const diffPercent = +((diffPixels / totalPixels) * 100).toFixed(4)
+
+  const diffBuffer = PNG.sync.write(diffPng)
+  await writeFile(diffMapPath, diffBuffer)
+  log(`diff ${diffPixels}/${totalPixels} px (${diffPercent}%) → ${diffMapPath}`)
+
+  // Token + geometry cross-check. Both files are emitted by sibling skills with
+  // the shape `{ tokens: {...}, geometry: {...} }` (sb-inspect-live for live,
+  // sb-validate-render for build). If either is missing we just skip token
+  // diffs — the pixel diff still tells the orchestrator something useful.
+  let structuredDiffs = []
+  let tokenDiffMeta = { compared: false, reason: 'tokens-not-supplied' }
+  if (TOKENS_LIVE && TOKENS_BUILD) {
+    const [liveJson, buildJson] = await Promise.all([
+      loadJsonIfPresent(TOKENS_LIVE),
+      loadJsonIfPresent(TOKENS_BUILD),
+    ])
+    if (liveJson && buildJson) {
+      const tokenDiffs = compareTokens(liveJson.tokens, buildJson.tokens)
+      const geometryDiffs = compareGeometryBlocks(liveJson.geometry, buildJson.geometry)
+      structuredDiffs = sortBySeverity([...tokenDiffs, ...geometryDiffs])
+      tokenDiffMeta = { compared: true, count: structuredDiffs.length }
+      log(`token cross-check: ${structuredDiffs.length} diff(s)`)
+    } else {
+      tokenDiffMeta = { compared: false, reason: 'tokens-unreadable' }
+    }
+  }
+
+  const passed = diffPercent <= THRESHOLD
+  const result = {
+    passed,
+    diffPercent,
+    diffPixels,
+    totalPixels,
+    threshold: THRESHOLD,
+    pixelThreshold: PIXEL_THRESHOLD,
+    diffMap: diffMapPath,
+    report: reportPath,
+    dimensions: {
+      live: { width: liveMeta.width || 0, height: liveMeta.height || 0 },
+      build: { width: buildMeta.width || 0, height: buildMeta.height || 0 },
+      canvas: { width: targetW, height: targetH },
+    },
+    tokenDiff: tokenDiffMeta,
+    structuredDiffs,
+    croppedLiveTo,
+    croppedBuildTo,
+    inputs: {
+      liveScreenshot: LIVE,
+      buildScreenshot: BUILD,
+      tokensLive: TOKENS_LIVE,
+      tokensBuild: TOKENS_BUILD,
+    },
+  }
+
+  await writeFile(reportPath, JSON.stringify(result, null, 2), 'utf8')
+  process.stdout.write(JSON.stringify(result))
+  process.stdout.write('\n')
+
+  // Exit 3 when the visual budget is blown. The full report is already on
+  // stdout + disk — the orchestrator parses it either way; the exit code is a
+  // shortcut for shell-level branching ("if compare; then ship; else re-roll").
+  process.exit(passed ? 0 : 3)
+}
+
+main().catch((err) => {
+  process.stderr.write(`[sb-compare-visual] fatal: ${err?.stack || err}\n`)
+  process.exit(1)
+})

package/templates/skills/sb-compare-visual/scripts/lib/compare-tokens.mjs

@@ -0,0 +1,273 @@
+// compare-tokens.mjs — pure token diffing.
+//
+// Consumes the `tokens` blocks emitted by sb-inspect-live (live-page measurement)
+// and sb-validate-render (build measurement) and produces a prioritized list of
+// structured differences. Pure functions, no I/O, no deps — fully unit-testable.
+//
+// Severity rubric:
+//   high    typography size mismatch on headings, brand color drift, viewport
+//           overflow regression — anything a user would notice at first glance.
+//   medium  body typography drift, button geometry drift, font-weight mismatch —
+//           visible but not jarring.
+//   low     line-height drift, font-family fallback divergence, container width
+//           jitter under a few pixels — pixel-peeping.
+
+const HEADING_FONT_SIZE_PX_TOLERANCE = 1
+const BODY_FONT_SIZE_PX_TOLERANCE = 1
+const BUTTON_HEIGHT_PX_TOLERANCE = 2
+const CONTAINER_WIDTH_PX_TOLERANCE = 5
+const LINE_HEIGHT_PX_TOLERANCE = 2
+const LINE_HEIGHT_UNITLESS_TOLERANCE = 0.1
+
+// Parse "24px", "1.5rem", "120%" → number-of-px (rough — assumes 1rem=16px,
+// 1em=16px, %=relative-of-16). The orchestrator passes computed styles which
+// are nearly always in px already; the rem/em/% paths are belt-and-braces.
+export function parsePx(value) {
+  if (value == null) return null
+  const s = String(value).trim().toLowerCase()
+  if (s === '' || s === 'auto' || s === 'none' || s === 'normal') return null
+  const m = s.match(/^(-?\d+(?:\.\d+)?)(px|rem|em|%)?$/)
+  if (!m) return null
+  const n = parseFloat(m[1])
+  const unit = m[2] || 'px'
+  if (unit === 'px') return n
+  if (unit === 'rem' || unit === 'em') return n * 16
+  if (unit === '%') return (n / 100) * 16
+  return null
+}
+
+// Parse line-height which may be unitless ("1.5"), px ("24px"), or normal.
+// Returns { kind: 'unitless'|'px'|'normal', value: number|null }.
+export function parseLineHeight(value) {
+  if (value == null) return { kind: 'normal', value: null }
+  const s = String(value).trim().toLowerCase()
+  if (s === '' || s === 'normal') return { kind: 'normal', value: null }
+  if (/^-?\d+(?:\.\d+)?$/.test(s)) return { kind: 'unitless', value: parseFloat(s) }
+  const px = parsePx(s)
+  if (px != null) return { kind: 'px', value: px }
+  return { kind: 'normal', value: null }
+}
+
+// Normalize colors to a comparable hex string. Accepts:
+//   #abc, #aabbcc, #aabbccdd, rgb(r,g,b), rgba(r,g,b,a), rgb(r g b / a), named.
+// Returns lowercase #rrggbb (alpha dropped — alpha drift is rarely brand-critical
+// and would explode the rule count). Returns null on unparseable input so the
+// caller can skip the comparison rather than emit a bogus diff.
+export function normalizeColor(value) {
+  if (value == null) return null
+  const s = String(value).trim().toLowerCase()
+  if (s === '' || s === 'transparent' || s === 'none' || s === 'currentcolor' || s === 'inherit') return null
+  if (s.startsWith('#')) {
+    const hex = s.slice(1)
+    if (/^[0-9a-f]{3}$/.test(hex)) return `#${hex[0]}${hex[0]}${hex[1]}${hex[1]}${hex[2]}${hex[2]}`
+    if (/^[0-9a-f]{4}$/.test(hex)) return `#${hex[0]}${hex[0]}${hex[1]}${hex[1]}${hex[2]}${hex[2]}`
+    if (/^[0-9a-f]{6}$/.test(hex)) return `#${hex}`
+    if (/^[0-9a-f]{8}$/.test(hex)) return `#${hex.slice(0, 6)}`
+    return null
+  }
+  const rgbMatch = s.match(/^rgba?\s*\(\s*([^)]+?)\s*\)$/)
+  if (rgbMatch) {
+    const parts = rgbMatch[1].split(/[\s,/]+/).filter(Boolean)
+    if (parts.length < 3) return null
+    const channels = parts.slice(0, 3).map((p) => {
+      if (p.endsWith('%')) return Math.round((parseFloat(p) / 100) * 255)
+      return Math.round(parseFloat(p))
+    })
+    if (channels.some((c) => !Number.isFinite(c) || c < 0 || c > 255)) return null
+    return '#' + channels.map((c) => c.toString(16).padStart(2, '0')).join('')
+  }
+  // Named colors aren't worth a full table here — caller skips when null.
+  return null
+}
+
+function familyHead(value) {
+  if (value == null) return null
+  return String(value)
+    .split(',')[0]
+    .trim()
+    .replace(/^['"]|['"]$/g, '')
+    .toLowerCase()
+}
+
+const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 }
+
+function pushDiff(diffs, area, issue, severity, extras = {}) {
+  diffs.push({ area, issue, severity, ...extras })
+}
+
+function compareTypography(area, live, build, fontSizeTol, sizeSeverity, diffs) {
+  if (!live || !build) return
+  if (live.present === false && build.present === false) return
+  if (live.present === false) {
+    pushDiff(diffs, area, `${area} present on build but missing on live`, 'medium')
+    return
+  }
+  if (build.present === false) {
+    pushDiff(diffs, area, `${area} present on live but missing on build`, 'high', {
+      liveText: live.text,
+    })
+    return
+  }
+  const lFs = parsePx(live['font-size'])
+  const bFs = parsePx(build['font-size'])
+  if (lFs != null && bFs != null && Math.abs(lFs - bFs) > fontSizeTol) {
+    pushDiff(diffs, area, `font-size ${build['font-size']} vs ${live['font-size']} expected`, sizeSeverity, {
+      live: live['font-size'],
+      build: build['font-size'],
+      deltaPx: +(bFs - lFs).toFixed(2),
+    })
+  }
+  if (live['font-weight'] && build['font-weight'] && String(live['font-weight']) !== String(build['font-weight'])) {
+    pushDiff(diffs, area, `font-weight ${build['font-weight']} vs ${live['font-weight']} expected`, 'medium', {
+      live: String(live['font-weight']),
+      build: String(build['font-weight']),
+    })
+  }
+  const lFam = familyHead(live['font-family'])
+  const bFam = familyHead(build['font-family'])
+  if (lFam && bFam && lFam !== bFam) {
+    pushDiff(diffs, area, `font-family ${bFam} vs ${lFam} expected`, 'low', { live: lFam, build: bFam })
+  }
+  const lLh = parseLineHeight(live['line-height'])
+  const bLh = parseLineHeight(build['line-height'])
+  if (lLh.value != null && bLh.value != null && lLh.kind === bLh.kind) {
+    const tol = lLh.kind === 'px' ? LINE_HEIGHT_PX_TOLERANCE : LINE_HEIGHT_UNITLESS_TOLERANCE
+    if (Math.abs(lLh.value - bLh.value) > tol) {
+      pushDiff(diffs, area, `line-height ${build['line-height']} vs ${live['line-height']} expected`, 'low', {
+        live: live['line-height'],
+        build: build['line-height'],
+      })
+    }
+  }
+  const lColor = normalizeColor(live.color)
+  const bColor = normalizeColor(build.color)
+  if (lColor && bColor && lColor !== bColor) {
+    pushDiff(diffs, area, `color ${bColor} vs ${lColor} expected`, 'high', { live: lColor, build: bColor })
+  }
+}
+
+function compareButton(live, build, diffs) {
+  if (!live || !build) return
+  if (live.present === false && build.present === false) return
+  if (live.present === false) {
+    pushDiff(diffs, 'button', 'button present on build but absent on live', 'low')
+    return
+  }
+  if (build.present === false) {
+    pushDiff(diffs, 'button', 'button present on live but absent on build', 'high')
+    return
+  }
+  // Rendered height is the most reliable size signal — `height: auto` on the
+  // computed style is uninformative; the bounding-rect height is what the user
+  // actually sees.
+  const lH = live.renderedH != null ? Number(live.renderedH) : parsePx(live.height)
+  const bH = build.renderedH != null ? Number(build.renderedH) : parsePx(build.height)
+  if (lH != null && bH != null && Math.abs(lH - bH) > BUTTON_HEIGHT_PX_TOLERANCE) {
+    pushDiff(diffs, 'button', `button height ${bH}px vs ${lH}px expected`, 'medium', {
+      live: lH,
+      build: bH,
+      deltaPx: +(bH - lH).toFixed(2),
+    })
+  }
+  const lBg = normalizeColor(live['background-color'])
+  const bBg = normalizeColor(build['background-color'])
+  if (lBg && bBg && lBg !== bBg) {
+    pushDiff(diffs, 'button', `background-color ${bBg} vs ${lBg} expected`, 'high', { live: lBg, build: bBg })
+  }
+  const lFg = normalizeColor(live.color)
+  const bFg = normalizeColor(build.color)
+  if (lFg && bFg && lFg !== bFg) {
+    pushDiff(diffs, 'button', `color ${bFg} vs ${lFg} expected`, 'high', { live: lFg, build: bFg })
+  }
+  const lBr = parsePx(live['border-radius'])
+  const bBr = parsePx(build['border-radius'])
+  if (lBr != null && bBr != null && Math.abs(lBr - bBr) > 1) {
+    pushDiff(diffs, 'button', `border-radius ${build['border-radius']} vs ${live['border-radius']} expected`, 'low')
+  }
+  const lFs = parsePx(live['font-size'])
+  const bFs = parsePx(build['font-size'])
+  if (lFs != null && bFs != null && Math.abs(lFs - bFs) > BODY_FONT_SIZE_PX_TOLERANCE) {
+    pushDiff(diffs, 'button', `font-size ${build['font-size']} vs ${live['font-size']} expected`, 'medium')
+  }
+}
+
+function compareContainer(live, build, diffs) {
+  if (!live || !build) return
+  const lW = live.computedRenderedW != null ? Number(live.computedRenderedW) : null
+  const bW = build.computedRenderedW != null ? Number(build.computedRenderedW) : null
+  if (lW != null && bW != null && Math.abs(lW - bW) > CONTAINER_WIDTH_PX_TOLERANCE) {
+    pushDiff(diffs, 'container', `container width ${bW}px vs ${lW}px expected`, 'low', {
+      live: lW,
+      build: bW,
+      deltaPx: +(bW - lW).toFixed(2),
+    })
+  }
+}
+
+function compareImages(live, build, diffs) {
+  if (!live || !build) return
+  const lc = Number(live.count || 0)
+  const bc = Number(build.count || 0)
+  if (lc !== bc) {
+    pushDiff(diffs, 'images', `image count ${bc} vs ${lc} expected`, lc > bc ? 'high' : 'medium', {
+      live: lc,
+      build: bc,
+    })
+  }
+}
+
+function compareGeometry(live, build, diffs) {
+  if (!live || !build) return
+  const lOver = !!live.viewportOverflow
+  const bOver = !!build.viewportOverflow
+  if (bOver && !lOver) {
+    pushDiff(diffs, 'geometry', 'build overflows the viewport but live does not', 'high')
+  } else if (!bOver && lOver) {
+    pushDiff(diffs, 'geometry', 'live overflows the viewport but build does not', 'low')
+  }
+  const lH = Number(live.totalHeight || 0)
+  const bH = Number(build.totalHeight || 0)
+  if (lH > 0 && bH > 0) {
+    const ratio = bH / lH
+    if (ratio < 0.7 || ratio > 1.4) {
+      pushDiff(diffs, 'geometry', `total height ${bH}px vs ${lH}px expected (${(ratio * 100).toFixed(0)}%)`, 'high', {
+        live: lH,
+        build: bH,
+      })
+    }
+  }
+}
+
+export function compareTokens(liveTokens, buildTokens) {
+  const diffs = []
+  if (!liveTokens || !buildTokens) return diffs
+
+  const live = liveTokens
+  const build = buildTokens
+
+  compareTypography('h1', live.h1, build.h1, HEADING_FONT_SIZE_PX_TOLERANCE, 'high', diffs)
+  compareTypography('h2', live.h2, build.h2, HEADING_FONT_SIZE_PX_TOLERANCE, 'high', diffs)
+  compareTypography('h3', live.h3, build.h3, HEADING_FONT_SIZE_PX_TOLERANCE, 'medium', diffs)
+  compareTypography('body', live.body, build.body, BODY_FONT_SIZE_PX_TOLERANCE, 'medium', diffs)
+  compareButton(live.button, build.button, diffs)
+  compareContainer(live.container, build.container, diffs)
+  compareImages(live.images, build.images, diffs)
+
+  return sortBySeverity(diffs)
+}
+
+export function compareGeometryBlocks(liveGeometry, buildGeometry) {
+  const diffs = []
+  compareGeometry(liveGeometry, buildGeometry, diffs)
+  return sortBySeverity(diffs)
+}
+
+// Stable sort: high first, then medium, then low. Within a severity, original
+// order is preserved (V8's Array.sort is stable since 2018).
+export function sortBySeverity(diffs) {
+  return [...diffs].sort((a, b) => {
+    const sa = SEVERITY_ORDER[a.severity] ?? 99
+    const sb = SEVERITY_ORDER[b.severity] ?? 99
+    return sa - sb
+  })
+}