similarbuild 0.1.0

package/templates/skills/sb-validate-render/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: sb-validate-render
+description: Renders a built fragment locally with the destination's theme reset injected, captures a mobile screenshot, and probes key tokens + geometry — the build → validate gate before any output reaches the user. Use when the SimilarBuild orchestrator (`/build-page`, `/build-site`, `/clip-section`) requests render validation after `sb-build-wp` or a Shopify build, or when the user asks to 'validate render' of a built file.
+---
+
+# sb-validate-render
+
+## Overview
+
+Closes the build → validate loop. Takes whatever `sb-build-wp` produced (HTML fragment) or a Shopify section build produced (Liquid file), wraps it in the destination CMS's blanket selectors, injects an aggressive theme reset, and renders it in headless chromium at a mobile viewport — simulating exactly what the user will see when they paste the fragment into the live destination. Captures a screenshot and probes the tokens and geometry the orchestrator needs to decide whether the build is faithful or needs a re-roll.
+
+This is the **non-negotiable gate** (bootstrap rule #4): nothing reaches the user without passing through here. Without the destination's theme reset, the local render lies — the fragment looks fine in isolation and falls apart on paste because the theme overrode font-weight, font-size, button styles, and image heights with `!important`.
+
+All deterministic work — Playwright launch, `setContent` (no `goto` — we have the HTML), reset injection, Liquid render with mock schema-default context, computed-style probe, screenshot — happens in `scripts/validate-render.mjs`. This SKILL.md only describes inputs, outputs, and failure handling.
+
+Act as the visual fidelity checkpoint. If the script returns suspicious output (tiny screenshot, missing wrapper, viewport overflow), surface that flag rather than passing garbage downstream to `sb-compare-visual`.
+
+## Inputs
+
+| Argument          | Required | Default       | Notes                                                                              |
+| ----------------- | -------- | ------------- | ---------------------------------------------------------------------------------- |
+| `file`            | yes      | —             | Path to the built fragment. HTML for `wp-elementor`, Liquid for `shopify-section`. |
+| `preset`          | yes      | —             | `wp-elementor` or `shopify-section`. Determines wrapper + reset.                   |
+| `output-dir`      | yes      | —             | Directory where `screenshot.png` and `render.json` are written.                    |
+| `viewport-width`  | no       | `390`         | Mobile-first. Override only if the orchestrator explicitly needs desktop.          |
+| `viewport-height` | no       | `844`         | iPhone 14-class default.                                                           |
+| `selector`        | no       | preset default | CSS selector to scope token probe + section bbox. Defaults to `.elementor` (WP) or `.page-width` (Shopify). |
+| `preset-yaml`     | no       | (auto)        | Override path to a preset YAML. Auto-detects `<plugin>/presets/{preset}.yaml` and falls back to a hardcoded baseline. |
+| `assets-map-path` | no       | —             | (preset=shopify-section only) Path to `assets-map.json` from `sb-extract-assets`. When supplied, `image_picker` settings without a `default` get populated from matching assetsMap entries (id-keyword → context-substring heuristic, data-URL inlined). Without this flag, those settings remain null and the `{% else %}` placeholder branch fires — which makes the rendered fragment show a neutral grey instead of the live photo, inflating the pixel diff by ~30pp with no actionable fix (Pattern #32). Pass it from the orchestrator whenever `target=shopify` and an assetsMap exists. |
+| `timeout`         | no       | `30000`       | Per-step timeout (ms).                                                             |
+
+## Output
+
+A single JSON object printed to stdout AND saved to `{output-dir}/render.json`:
+
+```json
+{
+  "file": "/abs/path/build.html",
+  "preset": "wp-elementor",
+  "viewport": { "width": 390, "height": 844 },
+  "probeRoot": ".elementor",
+  "screenshot": "{output-dir}/screenshot.png",
+  "tokens": {
+    "h1": { "present": true, "text": "...", "font-size": "24px", "font-weight": "300", "font-family": "...", "color": "..." },
+    "h2": { "present": true, "...": "..." },
+    "h3": { "present": false },
+    "body": { "font-size": "18px", "font-weight": "300", "...": "..." },
+    "button": { "present": true, "height": "...", "background-color": "...", "renderedH": 40, "...": "..." },
+    "images": { "count": 3, "sampled": [{ "src": "...", "computedHeight": "auto", "renderedH": 240, "hasInlineStyle": false }] },
+    "container": { "maxWidth": "...", "width": "...", "computedRenderedW": 390 }
+  },
+  "mockContext": { "populated": ["hero_image"], "skipped": [] },
+  "geometry": {
+    "totalHeight": 1420,
+    "totalWidth": 390,
+    "viewportInner": { "width": 390, "height": 844 },
+    "viewportOverflow": false,
+    "probeRoot": { "x": 0, "y": 0, "w": 390, "h": 1420 },
+    "sections": [{ "tag": "section", "classes": ["hero"], "bbox": {...} }]
+  },
+  "warnings": []
+}
+```
+
+The probed tokens are the **ground truth** for `sb-compare-visual` — pair them with `tokens_live` from `sb-inspect-live` to spot drift mechanically (e.g. h1 24px theme reset vs 32px expected from live).
+
+## Dependencies
+
+The host project must have:
+
+- `playwright` (with chromium browser — already installed by `sb-inspect-live` setup)
+- `js-yaml` — only when a preset YAML override is loaded (graceful skip if missing, falls back to hardcoded preset)
+- `liquidjs` — **only required when** `preset=shopify-section`. The script exits with an install hint if missing on the Shopify path. WP path doesn't need it.
+
+Node ≥ 20.
+
+## On Activation
+
+1. **Resolve inputs.** Collect `file`, `preset`, `output-dir`, plus optional `viewport-width`, `viewport-height`, `selector`, `preset-yaml`, `timeout`.
+
+2. **Ensure `output-dir` exists.** `mkdir -p` it.
+
+3. **Run the script.** From the project root:
+
+   ```bash
+   node {skill-root}/scripts/validate-render.mjs \
+     --file "{file}" \
+     --preset "{preset}" \
+     --output-dir "{output-dir}" \
+     [--viewport-width 390] \
+     [--viewport-height 844] \
+     [--selector "{css}"] \
+     [--preset-yaml "{path}"]
+   ```
+
+   The script handles: preset YAML resolution (`<plugin>/presets/{preset}.yaml` → hardcoded fallback), Liquid schema parsing + mock-context render (Shopify only, via liquidjs), wrapper injection (`<div class="elementor">` for WP, `<div class="page-width">` for Shopify), reset CSS injection, chromium launch with mobile viewport, `setContent` (NOT goto), font readiness wait, full-page screenshot, getComputedStyle probe of h1/h2/h3/body/button/images/container, and geometry capture (total height, viewport overflow, section bboxes). See `scripts/validate-render.mjs --help` for the full flag list.
+
+4. **Validate the result.** Parse stdout as JSON. If the script exits non-zero, surface stderr to the orchestrator and stop — don't fabricate output. Common stderr hints: `liquidjs` missing for Shopify, `playwright` missing or chromium not installed.
+
+5. **Inspect `warnings[]`.** A non-empty `warnings` array (e.g. tiny screenshot) is a soft signal of a failed render — pass through unchanged so the orchestrator can decide whether to treat it as a hard fail.
+
+6. **Return the JSON unchanged** to the caller. `sb-compare-visual` consumes `screenshot` and `tokens` directly. Do not summarize, mutate, or strip fields.
+
+## Failure modes
+
+| Symptom                                                  | Likely cause                                  | What to surface                                                                              |
+| -------------------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Script exits non-zero, stderr mentions `liquidjs`        | `preset=shopify-section` and liquidjs missing | Pass stderr verbatim. Suggest `npm i liquidjs`.                                              |
+| Script exits non-zero, stderr mentions `playwright`      | playwright/chromium not installed             | Pass stderr verbatim. Suggest `npm i playwright && npx playwright install chromium`.         |
+| `tokens.h1.present: false` for a hero-class section      | Wrong selector or build dropped the heading   | Surface to orchestrator — possibly a `sb-build-wp` defect, not a validate defect.            |
+| `geometry.viewportOverflow: true`                        | Fragment has `width > 100%` or fixed-px wider than viewport | Forward unchanged — high-severity finding for `sb-compare-visual` / `sb-review-checks`. |
+| `warnings[]` includes tiny-screenshot                    | Page didn't render (CSS error, throw in Liquid render) | Treat as hard fail; the screenshot is unusable for visual diff.                       |
+| Liquid schema JSON parse fails                           | Malformed `{% schema %}` block                | Script logs a warning and renders with empty mock context. Output is still produced; orchestrator may need to flag it. |
+
+## Conventions
+
+- Bare paths (e.g. `scripts/validate-render.mjs`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory.
+- `{project-root}` resolves to the project working directory.
+- `<plugin>/presets/{preset}.yaml` is read when present — populated by item #14 of the visual-migration plan; users can override per-theme. Skip silently when missing (the hardcoded fallback in the script matches the plan brief).

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

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+// test-validate-render.mjs — Smoke tests for validate-render.mjs.
+// Validates: --help works, missing args fail with exit 2, invalid presets are
+// rejected, and the in-script schema extractor + mock context builder behave.
+// Full-render tests (Playwright launch) are intentionally out of scope here —
+// they need chromium installed and would slow CI; covered by manual smoke runs.
+
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { dirname, resolve, join } from 'node:path'
+import { strict as assert } from 'node:assert'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const SCRIPT = resolve(here, '..', 'validate-render.mjs')
+
+let passed = 0
+let failed = 0
+
+function test(name, fn) {
+  try {
+    const result = fn()
+    if (result && typeof result.then === 'function') {
+      return result.then(
+        () => {
+          process.stdout.write(`ok - ${name}\n`)
+          passed++
+        },
+        (err) => {
+          process.stdout.write(`not ok - ${name}\n  ${err.message}\n`)
+          failed++
+        },
+      )
+    }
+    process.stdout.write(`ok - ${name}\n`)
+    passed++
+  } catch (err) {
+    process.stdout.write(`not ok - ${name}\n  ${err.message}\n`)
+    failed++
+  }
+}
+
+function run(args) {
+  return spawnSync('node', [SCRIPT, ...args], { encoding: 'utf8' })
+}
+
+// ---- 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, /validate-render\.mjs/)
+  assert.match(r.stdout, /--preset/)
+  assert.match(r.stdout, /wp-elementor/)
+  assert.match(r.stdout, /shopify-section/)
+})
+
+test('missing --file exits 2', () => {
+  const r = run(['--preset', 'wp-elementor', '--output-dir', '/tmp/x'])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /missing --file/)
+})
+
+test('missing --preset exits 2', () => {
+  const r = run(['--file', '/tmp/x.html', '--output-dir', '/tmp/x'])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /missing --preset/)
+})
+
+test('missing --output-dir exits 2', () => {
+  const r = run(['--file', '/tmp/x.html', '--preset', 'wp-elementor'])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /missing --output-dir/)
+})
+
+test('unknown preset exits 2', () => {
+  const r = run(['--file', '/tmp/x.html', '--preset', 'magento', '--output-dir', '/tmp/x'])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /unknown preset/)
+})
+
+test('non-numeric viewport exits 2', () => {
+  const r = run([
+    '--file',
+    '/tmp/x.html',
+    '--preset',
+    'wp-elementor',
+    '--output-dir',
+    '/tmp/x',
+    '--viewport-width',
+    'abc',
+  ])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /viewport must be numeric/)
+})
+
+// ---- Schema extraction + mock context (loaded as module) ----
+// The script's main() exits on import (top-level argv parsing), so we re-import
+// pieces we want to test by reading + evaluating the relevant functions in
+// isolation. Cleanest path: import the module under a flag where the missing
+// args path returns help. We instead use a small inline copy of the same logic
+// to keep tests deterministic and fast — the source-of-truth lives in the script.
+
+await test('schema extractor handles {% schema %} block', async () => {
+  // Import the script module just to get its source; we test behavior by
+  // re-implementing the regex inline (mirrored from validate-render.mjs).
+  const SCHEMA_RE = /\{%-?\s*schema\s*-?%\}([\s\S]*?)\{%-?\s*endschema\s*-?%\}/
+  const liquid = `<section>{{ section.settings.heading }}</section>
+{% schema %}
+{ "name": "Hero", "settings": [{ "id": "heading", "type": "text", "default": "Hello" }] }
+{% endschema %}`
+  const m = liquid.match(SCHEMA_RE)
+  assert.ok(m)
+  const parsed = JSON.parse(m[1])
+  assert.equal(parsed.settings[0].default, 'Hello')
+  const body = liquid.slice(0, m.index) + liquid.slice(m.index + m[0].length)
+  assert.match(body, /\{\{ section\.settings\.heading \}\}/)
+  assert.doesNotMatch(body, /schema/)
+})
+
+await test('schema extractor handles whitespace-trimming tags', () => {
+  const SCHEMA_RE = /\{%-?\s*schema\s*-?%\}([\s\S]*?)\{%-?\s*endschema\s*-?%\}/
+  const liquid = `<div></div>
+{%- schema -%}
+{ "name": "X" }
+{%- endschema -%}`
+  const m = liquid.match(SCHEMA_RE)
+  assert.ok(m, 'should match {%- schema -%} tags')
+})
+
+await test('schema extractor returns null when no schema present', () => {
+  const SCHEMA_RE = /\{%-?\s*schema\s*-?%\}([\s\S]*?)\{%-?\s*endschema\s*-?%\}/
+  const liquid = `<section>just liquid, no schema</section>`
+  const m = liquid.match(SCHEMA_RE)
+  assert.equal(m, null)
+})
+
+// ─── Pattern #32 — image_picker mock context (assets-map matching) ─────────
+// Mirror the heuristic table from validate-render.mjs so we can test the
+// matching behavior without importing the script (which exits on missing argv).
+
+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 || !Array.isArray(assetsMap.assets)) return null
+  const id = String(settingId).toLowerCase()
+  for (const rule of IMAGE_PICKER_ID_HEURISTICS) {
+    if (!rule.idRe.test(id)) continue
+    for (const a of assetsMap.assets) {
+      const c = String(a?.context || '').toLowerCase()
+      if (!c) continue
+      if (rule.ctxKeywords.some((kw) => c.includes(kw))) return a
+    }
+  }
+  for (const a of assetsMap.assets) {
+    if (String(a?.context || '').trim()) return a
+  }
+  return null
+}
+
+await test('Pattern #32: hero_image setting matches asset with context "ai-hero__bg"', () => {
+  const map = {
+    assets: [
+      { localPath: '/a/logo.png', context: 'header', ext: 'png' },
+      { localPath: '/a/photo.jpg', context: 'ai-hero__bg', ext: 'jpg' },
+    ],
+  }
+  const m = findAssetForImagePicker('hero_image', map)
+  assert.equal(m.localPath, '/a/photo.jpg')
+})
+
+await test('Pattern #32: logo setting matches asset with context "ai-hdr"', () => {
+  const map = {
+    assets: [
+      { localPath: '/a/photo.jpg', context: 'ai-hero__bg' },
+      { localPath: '/a/logo.png', context: 'ai-hdr__brand' },
+    ],
+  }
+  const m = findAssetForImagePicker('logo', map)
+  assert.equal(m.localPath, '/a/logo.png')
+})
+
+await test('Pattern #32: product_image matches asset with "ai-fp__gallery" context', () => {
+  const map = {
+    assets: [
+      { localPath: '/a/hero.jpg', context: 'ai-hero__bg' },
+      { localPath: '/a/p1.jpg', context: 'ai-fp__gallery__main' },
+    ],
+  }
+  const m = findAssetForImagePicker('product_image', map)
+  assert.equal(m.localPath, '/a/p1.jpg')
+})
+
+await test('Pattern #32: bare "hero" id matches asset with context "ai-hero"', () => {
+  const map = { assets: [{ localPath: '/a/h.jpg', context: 'ai-hero__bg' }] }
+  const m = findAssetForImagePicker('hero', map)
+  assert.equal(m.localPath, '/a/h.jpg')
+})
+
+await test('Pattern #32: id with no keyword match falls back to first asset with context', () => {
+  const map = {
+    assets: [
+      { localPath: '/a/img1.jpg', context: '' },
+      { localPath: '/a/img2.jpg', context: 'random-ctx' },
+      { localPath: '/a/img3.jpg', context: 'another-ctx' },
+    ],
+  }
+  // The id "background" doesn't match any heuristic rule → falls back to
+  // the first asset with non-empty context (skips the empty one).
+  const m = findAssetForImagePicker('background', map)
+  assert.equal(m.localPath, '/a/img2.jpg')
+})
+
+await test('Pattern #32: empty assetsMap returns null', () => {
+  assert.equal(findAssetForImagePicker('hero_image', { assets: [] }), null)
+  assert.equal(findAssetForImagePicker('hero_image', null), null)
+})
+
+await test('Pattern #32: setting id without keyword AND no contextful assets → null', () => {
+  const map = {
+    assets: [
+      { localPath: '/a/x.jpg', context: '' },
+      { localPath: '/a/y.jpg', context: '' },
+    ],
+  }
+  assert.equal(findAssetForImagePicker('background', map), null)
+})
+
+// ─── --assets-map-path CLI flag (pattern #32) ───────────────────────────────
+
+await test('Pattern #32: --assets-map-path appears in --help', () => {
+  const r = run(['--help'])
+  assert.equal(r.status, 0)
+  assert.match(r.stdout, /--assets-map-path/)
+})
+
+// ─── Pattern #24 — body probe scope-aware (browser-only, smoke noted) ───────
+// The actual probe runs in chromium via page.evaluate(probeInPage). We can't
+// run the in-browser logic from a node test without launching playwright,
+// which is intentionally out of scope for these smoke tests (test doc above).
+// Stub a node-side replica of the helper to confirm the search-order behavior.
+
+function findBodyLikeInScope(scopeRoot, doc, getDirectText) {
+  if (!scopeRoot || scopeRoot === doc.body) return null
+  const candidates = scopeRoot.querySelectorAll('p, span, div, li')
+  for (const el of candidates) {
+    const direct = getDirectText(el)
+    if (direct.replace(/\s+/g, '').length >= 1) return el
+  }
+  return null
+}
+
+await test('Pattern #24: findBodyLikeInScope finds first <p> with direct text', () => {
+  // Minimal mock — emulate the relevant slice of DOM API.
+  const fakeP = {
+    childNodes: [{ nodeType: 3, nodeValue: 'Hello world' }],
+  }
+  const fakeScope = {
+    querySelectorAll: (sel) => [fakeP],
+  }
+  const fakeDoc = { body: { /* unused */ } }
+  const getDirectText = (el) => {
+    let t = ''
+    for (const n of el.childNodes) if (n.nodeType === 3) t += n.nodeValue || ''
+    return t
+  }
+  const el = findBodyLikeInScope(fakeScope, fakeDoc, getDirectText)
+  assert.strictEqual(el, fakeP)
+})
+
+await test('Pattern #24: findBodyLikeInScope returns null when no body-like child has text', () => {
+  const fakeP = {
+    childNodes: [{ nodeType: 3, nodeValue: '   ' }], // whitespace only
+  }
+  const fakeScope = {
+    querySelectorAll: (_) => [fakeP],
+  }
+  const fakeDoc = { body: {} }
+  const getDirectText = (el) => {
+    let t = ''
+    for (const n of el.childNodes) if (n.nodeType === 3) t += n.nodeValue || ''
+    return t
+  }
+  assert.equal(findBodyLikeInScope(fakeScope, fakeDoc, getDirectText), null)
+})
+
+await test('Pattern #24: findBodyLikeInScope skips when scope IS document.body (legacy fallback)', () => {
+  const docBody = {}
+  const fakeDoc = { body: docBody }
+  assert.equal(findBodyLikeInScope(docBody, fakeDoc, () => ''), null)
+})
+
+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)