similarbuild 0.1.0

package/templates/memory/anti-patterns.md

@@ -0,0 +1,212 @@
+# Anti-patterns — bundled canon
+
+This file is the **bundled global canon** of build anti-patterns for the SimilarBuild framework. It is read by `sb-build-wp`, `sb-build-shopify`, and `sb-review-checks` via the cascade defined in Pattern #21:
+
+1. `<plugin>/memory/anti-patterns.md` (this file — versioned, distributed by the installer)
+2. `~/.claude/similarbuild-memory/anti-patterns.md` (per-user auto-learn — overrides/adds)
+3. `<skill>/references/*.md` (bundled fallback inside the skill itself — only when neither of the above exists)
+
+Each entry is **machine-parseable**: same shape, same fields, same order. `sb-review-checks` parses this file to drive its detection layer; `sb-build-{wp,shopify}` reads it to know what NOT to emit.
+
+---
+
+## Entry shape
+
+Every anti-pattern below has these fields, in this order:
+
+- **id** — stable identifier (`#1`..`#16`).
+- **name** — short human-readable title.
+- **applies-to** — `wp` | `shopify` | `any`.
+- **applies-when** — section type or composition context where the rule fires (`hero`, `button`, `image_picker fallback`, `any`, ...).
+- **symptom** — the visible failure when the anti-pattern slips through.
+- **fix-recipe** — concrete patch instruction (specific enough to feed `fixHints` to `sb-build-{wp,shopify}` programmatically).
+- **detector** — mechanical signal `sb-review-checks` uses (regex / AST shape / attribute presence). `process` means the check is enforced upstream by another skill, not by review-checks.
+- **severity** — `high` | `medium` | `low`.
+- **origin** — where this entry came from (bootstrap migration, smoke test phase + date, Shopify build construction, etc).
+
+---
+
+## Group 1 — Bootstrap canon (#1–#9)
+
+Distilled from the Alpha Infuse Shopify→WP migration (~50-turn live session). These are the structural failure modes that every WP/Elementor build has to defend against; most also apply 1:1 to Shopify with the Dawn theme reset substituting Elementor's.
+
+### #1 — Hero `100vh`
+
+- **applies-to:** any
+- **applies-when:** hero / full-bleed top section
+- **symptom:** mobile browser chrome (URL bar collapse, safe-area insets) makes `100vh` taller than the visible viewport, so the hero clips below the fold and CTAs are pushed off-screen.
+- **fix-recipe:** replace `height: 100vh` on the hero container with `aspect-ratio: 1 / 1.3; max-height: 700px` (mobile) and `aspect-ratio: 16 / 9; max-height: 720px` inside `@media (min-width: 1000px)`.
+- **detector:** any occurrence of `100vh` anywhere in the scope CSS.
+- **severity:** high
+- **origin:** bootstrap (Alpha Infuse migration)
+
+### #2 — `<img>` with `height: 100%` for full-bleed hero
+
+- **applies-to:** any
+- **applies-when:** hero / full-bleed image section
+- **symptom:** Elementor injects `img { height: auto !important }` (Dawn injects `img { max-width: 100%; height: auto; }`) which clobbers the inline height; the hero collapses to natural image height and breaks the section's intended aspect.
+- **fix-recipe:** replace the `<img>` hero with `background-image: url(...)` on the container; set `background-size: cover` and `background-position: center`; use the asset's `localPath` (WP) or `image_url` filter (Shopify).
+- **detector:** an `<img>` whose ancestor matches `class~="hero"` and whose inline `style` contains `height: 100%`.
+- **severity:** high
+- **origin:** bootstrap (Alpha Infuse migration)
+
+### #3 — Round-number opacity (eyeballed, not measured)
+
+- **applies-to:** any
+- **applies-when:** any overlay / scrim / faded layer
+- **symptom:** opacity values `0.3`, `0.5`, `0.7` are nearly always guesses; the live source's real reading is an arbitrary number like `0.42`, and the build looks "almost right but off".
+- **fix-recipe:** read the exact alpha from `inspection.tokens` or the inspected element's computed style; replace the round value with the literal token; mark `/* alpha from inspection */` once verified.
+- **detector:** regex `opacity\s*:\s*0?\.[357]` in any style block.
+- **severity:** low
+- **origin:** bootstrap (Alpha Infuse migration)
+
+### #4 — `a { color: inherit }` clobbering button color
+
+- **applies-to:** any
+- **applies-when:** any CTA rendered as `<a>` (or any anchor inside a scoped section)
+- **symptom:** the anchor inherits the themed ancestor color (`.elementor a { color: inherit !important }` on WP; `.shopify-section a { color: rgb(var(--color-link)) }` on Dawn), brand color is lost, link looks like body text.
+- **fix-recipe:** replace `color: inherit` with a literal hex from `inspection.tokens`; if the CTA must remain an `<a>`, set its color literally and chain the scope class as ancestor; prefer a real `<button>` for action affordances.
+- **detector:** any rule whose selector ends in `a` (or `a.x` / `a:hover`) with `color: inherit` in the body.
+- **severity:** medium
+- **origin:** bootstrap (Alpha Infuse migration)
+
+### #5 — `<button>` without defensive specificity (includes #5b: bare `!important`)
+
+This is the bundled defensive-specificity rule. Two failure modes share the same root cause; both are flagged here.
+
+- **applies-to:** any
+- **applies-when:** any styled `<button>` / `.btn` / `.cta` element
+- **symptom (#5):** theme `.elementor *` or `.shopify-section button` rules win over single-class selectors; the button reverts to theme-default appearance the moment Elementor or Dawn loads.
+- **symptom (#5b):** even with `!important`, a bare-selector rule still loses, because the theme has *both* ancestor specificity AND `!important` — yours has only `!important`.
+- **fix-recipe:** rewrite the selector with the scope class as ancestor AND double the modifier class (`.{scope} .{scope}__cta.{scope}__cta`); apply `!important` ONLY on the four font properties (`font-family`, `font-size`, `font-weight`, `color`) plus background and color when the theme bleeds through; never `!important` margins/paddings/widths/heights/transforms.
+- **detector (#5):** a rule whose selector contains `button|btn|cta`, has neither a descendant combinator (whitespace) nor a doubled class chain (`.x.x`), and styles background/color/font.
+- **detector (#5b):** a rule whose body contains `!important` and whose selector branches all lack a descendant combinator before the rightmost compound selector.
+- **severity:** high
+- **origin:** bootstrap (Alpha Infuse migration)
+
+### #6 — Overlap-image modeled as a sibling box
+
+- **applies-to:** any
+- **applies-when:** image-with-text overlap section (Pattern D)
+- **symptom:** the colored band behind the overlapping image is rendered as a sibling/box on the column wrapper instead of a `::before` on the section. Stacking is fragile, breaks at narrow widths, and the band's bounds don't match the live source.
+- **fix-recipe:** move the `::before` to the section selector; set `position: relative` on the section and `z-index: -1` on the `::before`; pull the band's `inset` values from `inspection.pseudoElements` (do not eyeball).
+- **detector:** a `::before` rule whose selector targets a `wrap|wrapper|container|inner` class with `position: absolute` + an inset/edge declaration.
+- **severity:** medium
+- **origin:** bootstrap (Alpha Infuse migration)
+
+### #7 — Showing output before validating in Playwright
+
+- **applies-to:** any
+- **applies-when:** any build, before delivery
+- **symptom:** the user sees a build that looks right in the file but renders wrong inside Elementor / Dawn because no aggressive theme reset was injected during preview; bugs surface only after the merchant pastes it in.
+- **fix-recipe:** every build must pass through `sb-validate-render` before being shown to the user; the skill injects an aggressive `.elementor *` (or `.shopify-section *`) reset and screenshots the rendered fragment for `sb-compare-visual` to diff.
+- **detector:** process — enforced by the orchestrator pipeline, not by review-checks.
+- **severity:** high
+- **origin:** bootstrap (Alpha Infuse migration)
+
+### #8 — Inline SVG impostor where a raster `<img>` belongs
+
+- **applies-to:** any
+- **applies-when:** any `<svg>` block whose visual intent is a real-world photo (product, hero, variant card)
+- **symptom:** a hand-drawn SVG approximating a product photo. Looks "off" and misses real-world detail (skin texture, packaging, lighting). Smells of LLM hallucination, not lived design.
+- **fix-recipe:** replace the `<svg>` with `<img src="{assetsMap[originalUrl].localPath}" alt="..." loading="lazy">`; the actual asset is already in `assetsMap`; inline SVG is reserved for icons that came from the source as SVG, not for raster impostors.
+- **detector:** an `<svg>` with `viewBox` whose larger dimension ≥ 400, ≥ 2 `<path>` children, and a `class` / parent class matching `product|photo|hero|image|card|variant`.
+- **severity:** medium
+- **origin:** bootstrap (Alpha Infuse migration)
+
+### #9 — Playwright headless can't trigger third-party widgets
+
+- **applies-to:** any
+- **applies-when:** inspection of a page with Klaviyo / GemPages / Yotpo / Shopify product-recommendation widgets
+- **symptom:** widget never renders during inspection, so the section appears empty in the build; LLM tries to fabricate URL or invent markup, producing broken output.
+- **fix-recipe:** fall back through the Plan B chain — try Playwright stealth (`playwright-extra` + `puppeteer-extra-plugin-stealth`) → ask the user for the URL of the same widget on an adjacent page that DOES respond → inspect that adjacent URL and lift markup. Never fabricate a substitute.
+- **detector:** process — enforced by `sb-inspect-live` (composite `widgetBlocked` signal in inspection JSON).
+- **severity:** high
+- **origin:** bootstrap (Alpha Infuse migration)
+
+---
+
+## Group 2 — Discovered during Shopify build construction (#10–#16)
+
+Surfaced during construction of `sb-build-shopify` (2026-05-04) and the must-fix bundle that followed (2026-05-04 → 2026-05-05). All Shopify-specific unless noted otherwise.
+
+### #10 — Schema setting `id` rename
+
+- **applies-to:** shopify
+- **applies-when:** any `{% schema %}` block, any setting / block setting
+- **symptom:** once a section ships, renaming a setting `id` orphans the merchant's edits — the new id reads as empty, and the merchant's prior values are silently lost.
+- **fix-recipe:** pick stable, semantic ids upfront (`heading`, not `top_text`; `cta_label`, not `button_1_text`); never rename across schema revisions; if the meaning genuinely changes, ship a new id alongside the old one and migrate via theme-app code.
+- **detector:** repository-level diff; not detectable from a single build. (Recommended future check in `sb-review-checks`: warn when a setting id contains UI-driven words like `top_`, `button_1_`, `text_2_`.)
+- **severity:** high (irreversible)
+- **origin:** sb-build-shopify construction (2026-05-04)
+
+### #11 — `image_picker` with `default`
+
+- **applies-to:** shopify
+- **applies-when:** any `image_picker` setting in `{% schema %}`
+- **symptom:** Shopify schema spec rejects `default` on `image_picker`. When silently accepted by older theme runtimes, the setting renders with a placeholder image that the merchant cannot easily replace ("logo random aparecendo até alguém trocar"), reading as a bug.
+- **fix-recipe:** emit `image_picker` settings WITHOUT `default`; expose the placeholder via the Liquid `{% if section.settings.X %} ... {% else %} ... {% endif %}` fallback; use the 208-byte base64 SVG placeholder (see #16) for the `{% else %}` branch.
+- **detector:** parse the schema JSON; flag any object where `type === "image_picker"` and `default` is present.
+- **severity:** high
+- **origin:** sb-build-shopify construction (2026-05-04)
+
+### #12 — Missing `presets`
+
+- **applies-to:** shopify
+- **applies-when:** any section
+- **symptom:** without at least one preset, the merchant cannot insert the section from "Add section" in the theme editor — it stays invisible in the picker. Section is technically valid but practically uninstallable.
+- **fix-recipe:** add at least one preset to the schema, using inspected values as the preset's defaults; reasonable categories: `Image`, `Text`, `Banners`, `Promotional`. Example: `"presets": [{ "name": "Hero — clone of source", "category": "Image" }]`.
+- **detector:** parse the schema JSON; flag when `presets` is missing or `presets.length === 0`.
+- **severity:** high
+- **origin:** sb-build-shopify construction (2026-05-04)
+
+### #13 — Missing `{{ block.shopify_attributes }}` on iterated block markup
+
+- **applies-to:** shopify
+- **applies-when:** any section with `{% for block in section.blocks %}` iteration
+- **symptom:** the editor cannot link the block UI to the rendered element — merchant clicks/drag/reorder produces no visible response, UI breaks silently. No error is raised.
+- **fix-recipe:** every block-iterated element must carry `{{ block.shopify_attributes }}` on the outermost element of its markup (e.g. `<article {{ block.shopify_attributes }}>`).
+- **detector:** for each `{% for block in section.blocks %}` ... `{% endfor %}` body, require at least one `{{ block.shopify_attributes }}` interpolation.
+- **severity:** high
+- **origin:** sb-build-shopify construction (2026-05-04)
+
+### #14 — Google Fonts `<link>` inside the section
+
+- **applies-to:** shopify
+- **applies-when:** any section that wants a custom typeface
+- **symptom:** technically renders, but Shopify owns `<head>` and the theme already loads fonts via `font_face` filter or theme settings. `<link>` inline duplicates the fetch on every page where the section appears, fights the theme's font-loading lifecycle, and makes the section feel un-Shopify.
+- **fix-recipe:** if the theme's font is acceptable, use `font-family: inherit` on headings + chain-scope-override only weight/size; if a custom font is genuinely required, expose it as a `font_picker` setting and consume via `{{ section.settings.X | font_face: font_display: 'swap' }}` inside `{% style %}`.
+- **detector:** any `<link rel="stylesheet" href="...fonts.googleapis.com...">` or `<link rel="preconnect" href="...fonts.gstatic.com">` in a Shopify build.
+- **severity:** medium
+- **origin:** sb-build-shopify construction (2026-05-04)
+
+### #15 — Hardcoded CDN URLs in markup
+
+- **applies-to:** shopify
+- **applies-when:** any `<img>`, `<source>`, or `url(...)` referencing an external CDN
+- **symptom:** hardcoded `cdn.shopify.com/...` or `cdn.{theme}.com/...` paths bypass Shopify's image transformation pipeline (no `image_url: width: N` variants), break when the merchant uploads a different asset, and orphan when the source CDN expires the URL.
+- **fix-recipe:** for setting-driven images use `{{ section.settings.X | image_url: width: N }}` (and the corresponding `srcset` with multiple widths); for fallbacks use the base64 SVG placeholder (#16); never emit a literal `https://cdn...` URL.
+- **detector:** regex `https?://[^"']*\.(shopify|cdn|cloudfront|cloudinary)[^"']*\.(jpg|jpeg|png|webp|gif|svg)` in markup.
+- **severity:** high
+- **origin:** sb-build-shopify construction (2026-05-04)
+
+### #16 — Developer filesystem paths in fallbacks
+
+- **applies-to:** any
+- **applies-when:** any fallback path in markup or CSS (`<img src>`, `url(...)`, `image_picker {% else %}` branch, default for a `text` setting, etc.)
+- **symptom:** absolute filesystem paths from the developer's machine (`/Users/<dev>/...`, `/home/<dev>/...`, `C:\Users\...`) leak into distributable output; (a) `sb-validate-render` cannot resolve the path (no `file://` document base, Chromium blocks cross-origin), so the build screenshot shows a black rectangle and inflates `sb-compare-visual` diff%; (b) the path is meaningless on any other machine — merchant install, CI, another teammate.
+- **fix-recipe:** represent fallbacks as one of (a) **base64 data URLs** for small placeholders (≤500 bytes — preferred for MVP); (b) URLs from the platform's CDN (Shopify `image_url` filter, theme assets); (c) empty settings that force the merchant to choose. The canonical placeholder for `image_picker` `{% else %}` branches is a 208-byte SVG (1170×900, fill `#d4d4d4`):
+  ```
+  data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMTcwIDkwMCIgcHJlc2VydmVBc3BlY3RSYXRpbz0ieE1pZFlNaWQgc2xpY2UiPjxyZWN0IHdpZHRoPSIxMTcwIiBoZWlnaHQ9IjkwMCIgZmlsbD0iI2Q0ZDRkNCIvPjwvc3ZnPg==
+  ```
+- **detector:** regex `/(Users|home|opt)/[^/"'\s]+/` or `[A-Z]:\\(Users|Documents)\\` anywhere in the build output.
+- **severity:** high
+- **origin:** sb-build-shopify must-fix bundle (2026-05-04, generalized 2026-05-05)
+
+---
+
+## Maintenance
+
+- New entries get appended in a new group with a header naming the discovery context and date.
+- Numbering is stable and additive — never renumber.
+- When an entry's detector becomes obsolete (e.g. the underlying tooling fixes it upstream), mark `detector: process` and add a `superseded-by:` note instead of deleting; the historical context is what makes the canon worth keeping.

package/templates/memory/design-knowledge.md

@@ -0,0 +1,225 @@
+# Design knowledge — bundled canon
+
+This file is the **bundled global canon** of accessibility, performance, and web-standards checks for the SimilarBuild framework. It is read by `sb-review-checks` (the structural validator) and consulted by `sb-build-{wp,shopify}` when emitting markup, via the cascade defined in Pattern #21:
+
+1. `<plugin>/memory/design-knowledge.md` (this file — versioned, distributed by the installer)
+2. `~/.claude/similarbuild-memory/design-knowledge.md` (per-user auto-learn — overrides/adds)
+3. `<skill>/references/review-rules.md` (bundled fallback inside `sb-review-checks` itself — only when neither of the above exists)
+
+These checks are **not opinions** — they are baselines every production fragment must clear. Each entry pairs a mechanical detector (regex / DOM shape) with a concrete fix template that `sb-review-checks` can emit as a `candidateFix` specific enough for `sb-build-{wp,shopify}` to apply programmatically. Generic prose ("improve specificity", "fix accessibility") is forbidden — that is the failure mode this layer exists to prevent.
+
+The structural detectors do the mechanical work; the LLM judges semantic quality (is the alt text *meaningful*? is the heading hierarchy *coherent given content*?). Both layers run on every build.
+
+---
+
+## Entry shape
+
+Every check below has these fields, in this order:
+
+- **id** — stable identifier (`a11y-...`, `perf-...`, `web-...`).
+- **name** — short human-readable title.
+- **group** — `a11y` | `performance` | `web-standards`.
+- **applies-to** — `wp` | `shopify` | `any` (some checks are preset-specific; flagged here).
+- **applies-when** — composition context where the check fires.
+- **symptom** — the user-visible failure when the check is missed.
+- **fix-recipe** — concrete patch instruction (must be specific enough to feed `fixHints` to `sb-build-{wp,shopify}` programmatically).
+- **detector** — mechanical signal (DOM query, regex, attribute presence/absence).
+- **severity** — `high` | `medium` | `low`.
+- **origin** — provenance (web-standards baseline, framework smoke test discovery, etc).
+
+---
+
+## Group A — Accessibility (5 checks)
+
+### a11y-img-alt — `<img>` missing `alt`
+
+- **id:** a11y-img-alt
+- **group:** a11y
+- **applies-to:** any
+- **applies-when:** any `<img>` element in the markup.
+- **symptom:** screen readers either skip the image entirely or read a useless filename; the section becomes unusable for non-sighted users.
+- **fix-recipe:** add `alt="<short description>"` (8–12 words, what the image conveys, not what it shows literally) for content images; add `alt=""` (empty, intentional) for decorative images. Source: `inspection.imgUrls[].alt` if present, else surrounding-context inference.
+- **detector:** any `<img>` with no `alt` attribute. (Empty `alt=""` is fine — it's the intentional declaration of "decorative".)
+- **severity:** high
+- **origin:** WCAG 2.1 SC 1.1.1 (Non-text Content)
+
+### a11y-button-aria — icon-only `<button>` without `aria-label`
+
+- **id:** a11y-button-aria
+- **group:** a11y
+- **applies-to:** any
+- **applies-when:** any `<button>` whose visible text is empty or a single emoji/glyph (`☰`, `×`, `→`).
+- **symptom:** screen readers announce "button" with no purpose; the action is invisible to non-sighted users.
+- **fix-recipe:** add `aria-label="<inferred action>"` — `Close`, `Open menu`, `Search`, `Add to cart`. If the label might be merchant-edited (Shopify), expose an `aria_label` text setting alongside.
+- **detector:** a `<button>` whose `textContent.trim()` is empty (or one emoji/glyph) AND has no `aria-label` AND no `aria-labelledby` AND no inner `<img alt="non-empty">`.
+- **severity:** high
+- **origin:** WCAG 2.1 SC 4.1.2 (Name, Role, Value)
+
+### a11y-heading-hierarchy — broken outline
+
+- **id:** a11y-heading-hierarchy
+- **group:** a11y
+- **applies-to:** any
+- **applies-when:** any section emitting headings.
+- **symptom:** screen readers' heading-jump navigation produces a confusing structure; SEO crawlers struggle to extract the page's outline.
+- **fix-recipe:** specific to the case — demote a duplicated `<h1>` to `<h2>`, raise a `<h3>` to `<h2>` when nothing precedes it, fill in the skipped level. The orchestrator may signal that this is a sub-section that should start at `<h2>` (not `<h1>`) — respect that.
+- **detector:** three sub-checks: (1) first heading is `<h3>` or deeper with no `<h1>` / `<h2>` above → severity medium. (2) multiple `<h1>` elements in the same section → severity medium. (3) skip in level (`<h2>` followed directly by `<h4>`) → severity low.
+- **severity:** medium (default; case (3) is low)
+- **origin:** WCAG 2.1 SC 1.3.1 (Info and Relationships)
+
+### a11y-button-type — `<button>` without explicit `type`
+
+- **id:** a11y-button-type
+- **group:** a11y
+- **applies-to:** any
+- **applies-when:** any `<button>` element.
+- **symptom:** the implicit `type` is `submit` — clicking the button can submit a parent form unexpectedly. Elementor pages often have hidden forms; Shopify product pages have add-to-cart forms; either silently swallows the click and triggers a submit.
+- **fix-recipe:** add `type="button"` to every `<button>` that isn't explicitly a form submit (which should be vanishingly rare in section markup).
+- **detector:** `<button>` with no `type` attribute, OR with a non-standard value (anything other than `button` / `submit` / `reset`).
+- **severity:** medium
+- **origin:** HTML spec (default `type=submit` is a footgun)
+
+### a11y-nav-semantic — main navigation as `<div>`
+
+- **id:** a11y-nav-semantic
+- **group:** a11y
+- **applies-to:** any
+- **applies-when:** the section emits a navigation region.
+- **symptom:** screen readers' "skip to navigation" landmarks miss the region; keyboard users can't jump past it.
+- **fix-recipe:** change `<div class="nav...">` to `<nav class="nav..." aria-label="Main">`. Use `aria-label` to disambiguate when the page has multiple `<nav>` regions (header nav, footer nav, sidebar).
+- **detector:** a `<div>` with class containing `nav|menu|navigation` (excluding `footer|sub|breadcrumb`) that contains ≥ 2 `<a>` children and is NOT inside a `<nav>`.
+- **severity:** medium
+- **origin:** WCAG 2.1 SC 1.3.1 + ARIA Authoring Practices (Landmarks)
+
+---
+
+## Group B — Performance (4 checks)
+
+### perf-img-lazy — non-hero `<img>` without `loading="lazy"`
+
+- **id:** perf-img-lazy
+- **group:** performance
+- **applies-to:** any
+- **applies-when:** any `<img>` that is not the hero image.
+- **symptom:** below-the-fold images load eagerly, competing with critical resources; LCP and TBT both regress.
+- **fix-recipe:** add `loading="lazy"` to every non-hero `<img>`. The hero image stays `loading="eager"` (and on Shopify, also `fetchpriority="high"`).
+- **detector:** an `<img>` that is NOT the hero (heuristic: lacks `fetchpriority="high"`, has no ancestor class containing `hero`, and is not the first `<img>` in the document) AND does not declare `loading="lazy"` or `loading="eager"`.
+- **severity:** medium
+- **origin:** Web.dev / Core Web Vitals (LCP optimization)
+
+### perf-hero-preload — hero without preload link
+
+- **id:** perf-hero-preload
+- **group:** performance
+- **applies-to:** wp (Shopify owns `<head>`-level preloading; sections must NOT emit `<link rel="preload">`)
+- **applies-when:** any WP build where the hero is identifiable.
+- **symptom:** the LCP image fetch starts only after the CSS / image-element parse phase completes; LCP is delayed by hundreds of ms.
+- **fix-recipe:** add `<link rel="preload" as="image" href="{heroUrl}">` at the top of the fragment. `heroUrl` is the `localPath` of the asset OR the URL inside the first matching CSS `background-image` rule.
+- **detector:** two-step (Pattern #25 — without it, builds with CSS `background-image` heroes get a false positive on the logo `<img>`):
+  - **Step 1 — CSS background-image hero.** Scan the scope CSS for a rule whose selector is a single root-scope class (`.foo` or `.foo:pseudo`, no descendant combinator, no `__` BEM modifier) and whose body declares `background-image: url(...)`. The `url(...)` of the FIRST matching rule IS the hero — verify a `<link rel="preload" as="image" href="<bg-url>">` exists; flag against that URL otherwise.
+  - **Step 2 — `<img>` hero (only when no CSS-bg hero was found).** Confidence-tiered: `fetchpriority="high"` → ancestor class containing `hero` → `src` / `alt` contains `hero|banner|cover` → declared width ≥ 800px → first `<img>` (last resort, **skipped** here so logos don't false-positive).
+  - **Step 3 — neither matches.** Skip the check entirely. No false positive on pages without an obvious hero.
+- **severity:** medium
+- **origin:** Web.dev (LCP). Detector refined post-smoke (fixes.md #25, 2026-05-05).
+
+### perf-font-display — Google Fonts without `&display=swap`
+
+- **id:** perf-font-display
+- **group:** performance
+- **applies-to:** wp (Shopify build emits no Google Fonts links — anti-pattern #14)
+- **applies-when:** the WP build references Google Fonts via `<link rel="stylesheet">`.
+- **symptom:** FOIT (flash of invisible text) — the page renders blank typography until the font loads, causing perceived slowness and a CLS spike when the system font swaps to the web font.
+- **fix-recipe:** append `&display=swap` to the `href` query string of the Google Fonts stylesheet link.
+- **detector:** `<link rel="stylesheet" href="...fonts.googleapis.com...">` whose href has no `display=swap` query parameter.
+- **severity:** medium
+- **origin:** Web.dev (FOIT/FOUT, font-display)
+
+### perf-fetchpriority-hero — Shopify hero without `fetchpriority="high"`
+
+- **id:** perf-fetchpriority-hero
+- **group:** performance
+- **applies-to:** shopify
+- **applies-when:** the Shopify build emits a hero `<img>` (settings-driven, `image_url` filter).
+- **symptom:** without `fetchpriority`, the hero competes with theme assets in the browser's prioritization queue; LCP regresses by ~100–300ms on slower networks.
+- **fix-recipe:** add `fetchpriority="high"` to the hero `<img>` (alongside `loading="eager"`).
+- **detector:** the hero `<img>` (identified by the same confidence tier as `perf-hero-preload` step 2) has no `fetchpriority="high"`.
+- **severity:** low
+- **origin:** Web.dev (Priority Hints — LCP optimization)
+
+---
+
+## Group C — Web standards (3 checks)
+
+### web-srcset-responsive — wide `<img>` without `srcset`
+
+- **id:** web-srcset-responsive
+- **group:** web-standards
+- **applies-to:** any
+- **applies-when:** an `<img>` with explicit width > 800px (via `width="..."` attribute or inline `style="width: ...px"`).
+- **symptom:** mobile devices download the desktop-sized asset; bandwidth waste, slower paint, worse LCP on cellular.
+- **fix-recipe:** add `srcset` with multiple widths + `sizes` directive. WP: feed widths from `inspection.imgUrls[].naturalWidth` and `srcset` candidates from `assetsMap`. Shopify: use `{{ image | image_url: width: N }}` for each candidate width (Shopify CDN auto-generates variants); `sizes` value `"(min-width: 1000px) 50vw, 100vw"` for half-width desktop content, `"100vw"` for full-bleed.
+- **detector:** an `<img>` with explicit width > 800px AND no `srcset` attribute. (Without an explicit width we don't flag — too noisy on intrinsic-sized images.)
+- **severity:** low
+- **origin:** HTML5 (`<img srcset sizes>`)
+
+### web-modal-dialog — modal as `<div>`
+
+- **id:** web-modal-dialog
+- **group:** web-standards
+- **applies-to:** any
+- **applies-when:** any modal / lightbox markup.
+- **symptom:** custom-rolled `<div role="dialog">` modals miss `Esc`-to-close, focus trapping, the inert outer page, and the native `::backdrop` styling — keyboard and screen-reader users are stranded.
+- **fix-recipe:** change `<div class="modal" role="dialog">` to `<dialog class="modal">`. Open with `dialog.showModal()`, close with `dialog.close()`. Style the backdrop via `dialog::backdrop`. No library, no custom focus-trap.
+- **detector:** a `<div>` with `role="dialog"` OR class containing `modal` that is NOT inside a `<dialog>`.
+- **severity:** medium
+- **origin:** HTML Living Standard (`<dialog>`) + WCAG 2.1 SC 2.1.2 (No Keyboard Trap)
+
+### web-preconnect-fonts — Google Fonts without preconnect
+
+- **id:** web-preconnect-fonts
+- **group:** web-standards
+- **applies-to:** wp (Shopify build emits no Google Fonts links — anti-pattern #14)
+- **applies-when:** the WP build emits at least one `<link rel="stylesheet" href="...fonts.googleapis.com...">`.
+- **symptom:** the browser establishes the TLS handshake with `fonts.googleapis.com` and `fonts.gstatic.com` only when the stylesheet starts parsing; ~150–300ms of head-of-line blocking before the font request fires.
+- **fix-recipe:** add the missing `<link rel="preconnect">` entries before the stylesheet — `<link rel="preconnect" href="https://fonts.googleapis.com">` and `<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>`. The `crossorigin` attribute on `gstatic` is mandatory (the actual font files are CORS-fetched).
+- **detector:** at least one `<link rel="stylesheet" href="...fonts.googleapis.com...">` exists, but no preconnect to `fonts.googleapis.com` AND/OR `fonts.gstatic.com` precedes it.
+- **severity:** low
+- **origin:** Web.dev (Resource hints — preconnect)
+
+---
+
+## Cross-reference layer (when `--compare-diffs` is supplied to `sb-review-checks`)
+
+Not a separate check list — a layer applied on top of groups A, B, C.
+
+- For each violation, look up its `location` against high-severity entries in `compareDiffs.structuredDiffs`. If they overlap (e.g. a button-related violation and a high-severity button color diff), **escalate** the violation to `severity: high` and tag with `correlatedDiff`.
+- For each high-severity diff with no static-rule backing, **synthesize** a violation directly from the diff measurements so it joins the prioritized list. Its `candidateFix` names the concrete value to change ("update `h1` from build value `24px` to live-page value `27px`").
+- Result: one prioritized list. The orchestrator never has to reason across two parallel sources.
+
+---
+
+## Output contract
+
+Every emitted violation has the shape:
+
+```json
+{
+  "group": "a11y" | "performance" | "web-standards" | "anti-pattern" | "visual-diff" | "design-quality",
+  "id": "a11y-button-aria" | "#5b" | "diff-h1",
+  "location": "selector `…`" | "<tag …>" | "style block line N",
+  "issue": "<one-sentence human-readable description of the problem>",
+  "candidateFix": "<specific patch instruction — names the selector/attribute/property>",
+  "severity": "high" | "medium" | "low",
+  "correlatedDiff": { "area": "…", "issue": "…", "deltaPx": -3 }
+}
+```
+
+Hard rule (machine-parseability — Pattern #34): `candidateFix` MUST be specific enough that `sb-build-{wp,shopify}` can apply it programmatically as a `fixHint`. Generic prose is forbidden — that is the failure mode this layer exists to prevent.
+
+---
+
+## Maintenance
+
+- New checks append within their group, with a stable id (`a11y-X`, `perf-X`, `web-X`).
+- When a baseline shifts (new browser landing, WCAG update), update the affected entry in place and bump the file's frontmatter version (handled by the installer's auto-learn merge).
+- Removing a check (e.g. browsers eliminate the underlying problem) — keep the entry, mark `severity: deprecated`, and note the date / browser version that obviated it; never silently delete.

package/templates/memory/fixes.md

@@ -0,0 +1,163 @@
+# Fix recipes — bundled canon
+
+This file is the **bundled global canon** of cross-skill fix recipes for the SimilarBuild framework. It captures the eleven framework-level fixes (Padrões #22–#32 from the build roadmap plan) discovered during smoke testing, codified so that future iterations of the framework — and skills that auto-learn from new sites — have a structured reference.
+
+Read by `sb-build-{wp,shopify}` (when `fixHints` from `sb-review-checks` reference one of these IDs), by `sb-review-checks` (to phrase its `candidateFix` strings consistently), and by maintainers extending the framework. Cascade order is the same as the other memory files (Pattern #21):
+
+1. `<plugin>/memory/fixes.md` (this file — versioned, distributed by the installer)
+2. `~/.claude/similarbuild-memory/fixes.md` (per-user auto-learn — overrides/adds)
+3. Skill-internal patterns (where applicable)
+
+---
+
+## Entry shape
+
+Every fix below has these fields, in this order:
+
+- **id** — stable identifier (`#22`..`#32`).
+- **name** — short title summarizing the fix.
+- **applies-to** — which skill(s) the fix lives in (`sb-inspect-live`, `sb-validate-render`, `sb-compare-visual`, `sb-review-checks`, `sb-build-shopify`, orchestrator, ...).
+- **applies-when** — the failure signature that should trigger this recipe.
+- **symptom** — what was breaking before the fix, in user-visible / metric terms.
+- **fix-recipe** — the actual change made, named at the level of file + helper + behavior. Specific enough that a maintainer can re-apply it from scratch on a new branch.
+- **detector** — how a future regression would be caught (test name, smoke metric, or "process — caught by skill X").
+- **origin** — discovery context + date.
+
+The IDs `#22`–`#32` are stable framework-wide and align 1:1 with the "Padrões emergidos durante a construção" / "Anti-patterns descobertos pelo smoke test" sections of the build plan. Numbers below `#22` are non-fix learnings (composition patterns, output conventions) and live elsewhere.
+
+---
+
+## #22 — DPR alignment cross-skill
+
+- **id:** #22
+- **name:** Cross-skill device-pixel-ratio alignment
+- **applies-to:** sb-validate-render, sb-inspect-live, sb-compare-visual
+- **applies-when:** comparing a build screenshot to a live screenshot, where one was captured at DPR 1 and the other at DPR 3 (or any mismatch).
+- **symptom:** screenshots have different intrinsic dimensions (live 1170w, build 780w in the example-store case) → `sb-compare-visual`'s pad-to-canvas path detects the entire offset region as diff → diff% inflated by tens of percentage points without any genuine fidelity issue. Smoke example-store hero: 94.88% → 52.2% on this fix alone (-42.68pp).
+- **fix-recipe:** in `sb-validate-render/scripts/validate-render.mjs`, set `deviceScaleFactor: 3` on the Playwright context to match `sb-inspect-live`'s iPhone 14 device profile; add a comment naming Pattern #22; do NOT scale via CSS — set DPR at the browser context level so screenshot intrinsic dimensions match.
+- **detector:** smoke metric — diff% on a known-good build should not regress past the post-#22 baseline. No unit test alters DPR explicitly; check is via the smoke pipeline.
+- **origin:** smoke test `/build-page example-store.com` (2026-05-04)
+
+## #23 — `widgetBlocked` composite signal
+
+- **id:** #23
+- **name:** Multi-signal `widgetBlocked` heuristic
+- **applies-to:** sb-inspect-live
+- **applies-when:** any inspection of a real page; the legacy single-signal `bodyHtmlLen < 1024` heuristic fired false positives on minimalist real pages (`example.com` 528B, `info.cern.ch` 646B).
+- **symptom:** `widgetBlocked: true` reported on legitimate pages → orchestrator escalates / aborts unnecessarily; user gets a "site blocked" message for a site that loads fine.
+- **fix-recipe:** in `inspect-live.mjs`, replace the size-only check with a composite signal — flag `widgetBlocked=true` when ANY of: (a) `bodyHtmlLen < 256` (extreme-tiny — real pages always exceed); (b) match against expanded `BLOCK_PATTERNS` regex on body innerText (`/just a moment/`, `/checking your browser/`, `/captcha/`, `/forbidden/`, ...); (c) match against new `BLOCK_TITLE_PATTERNS` on `<title>` (Cloudflare's "Just a moment...", "Attention Required! | Cloudflare", "Access Denied"); (d) `bodyHtmlLen` 256–1024 AND `meaningfulChildren < 2` (small AND structurally bare = challenge page).
+- **detector:** 9 unit tests in `test-inspect-live.mjs` covering example.com (NOT blocked), info.cern.ch (NOT blocked), extreme-tiny (blocked), small-and-bare (blocked), Cloudflare title-only (blocked), captcha keyword (blocked), large legitimate page (NOT blocked).
+- **origin:** smoke test follow-up (2026-05-05)
+
+## #24 — Token probe scope-aware
+
+- **id:** #24
+- **name:** Validate-render token probe respects fragment scope
+- **applies-to:** sb-validate-render
+- **applies-when:** the rendered fragment uses scope class `.X` and the probe needs to read body-like typography from inside that scope, not from the global `<body>` HTML element.
+- **symptom:** `tokens_build.body` returned `"Times"` / `"Times New Roman"` (the UA default for the bare HTML test page wrapping the fragment) instead of the scope's actual font; `sb-compare-visual`'s token cross-check then reported a phantom font-family mismatch.
+- **fix-recipe:** in `validate-render.mjs`'s `probeInPage`, add `findBodyLikeInScope(scopeRoot)` helper. Search order: (1) first `<p>/<span>/<div>/<li>` inside the scope with non-empty direct text content; (2) the scope root itself when not `document.body`; (3) `document.body` (legacy fallback). Use the resulting element as `bodyEl` for `getComputedStyle`. The token reflects real fragment typography, not UA default.
+- **detector:** 3 stub tests + 1 CLI test in `test-validate-render.mjs` cover helper logic (mocked); browser-driven E2E pending real chromium smoke run.
+- **origin:** smoke test follow-up (2026-05-05)
+
+## #25 — `perf-hero-preload` two-step detection
+
+- **id:** #25
+- **name:** Hero detection — CSS background first, `<img>` confidence-tiered second
+- **applies-to:** sb-review-checks
+- **applies-when:** a build uses Pattern B (Full-bleed hero with `background-image`) and the check needs to know whether to flag a missing `<link rel="preload">`.
+- **symptom:** the legacy single-step check picked the FIRST `<img>` in the fragment as "hero" — typically the logo — and flagged missing preload even when the correct `<link rel="preload" as="image">` for the background-image hero was present at the top of the file. False positive emitted as a misleading `candidateFix`.
+- **fix-recipe:** in `scripts/lib/design-quality.mjs`, replace `checkHeroPreload` with a three-tier detector: (1) `findHeroCssBackgroundImage(css)` — first CSS rule whose selector is a single root-class (`.foo` or `.foo:pseudo`, no descendant combinator, no `__` BEM modifier) and whose body declares `background-image: url(...)`; flag if no preload matching that URL. (2) `findHeroImgWithConfidence($)` returning a tier — `explicit` (fetchpriority=high), `hero-ancestor` (class match), `name-match` (src/alt match `hero|banner|cover`), `wide` (width≥800), `fallback` (first `<img>`); SKIP the check when tier is `fallback` to avoid logo false positives. (3) Neither matches → skip silently.
+- **detector:** 8 new tests in `test-design-quality.mjs` covering CSS-bg + preload present/absent, hero-bg + LOGO together (flag only the bg), bare-first-img skip, `<img>` ≥800px (flag), BEM-modifier rejection, descendant-combinator rejection, comma-selectors, pseudo-class.
+- **origin:** smoke test follow-up (2026-05-05)
+
+## #26 — Scope-aware comparison (orchestrator passes bbox)
+
+- **id:** #26
+- **name:** Orchestrator forwards section boundingBox into the comparator
+- **applies-to:** orchestrator (`/build-page`, `/build-site`, `/clip-section`), sb-compare-visual, sb-inspect-live
+- **applies-when:** the build composes a single section (e.g. hero ~2500px tall) but the live screenshot is a full-page capture (~17000px). Without bbox awareness, padding-to-canvas paints every live-only region as diff and inflates diff% by ~38pp.
+- **symptom:** comparing a section build against a full-page live screenshot reports diff% of "scope mismatch" rather than fidelity drift; `sb-build-*` cannot react meaningfully because there's no real defect to fix.
+- **fix-recipe:** generalize the pattern as "wide-capture skill A → narrow-consume skill B passes A's bbox to B for cropping before measurement". Concretely: `sb-inspect-live` exposes `sectionBoundingBox` (BFS find of first section-signature descendant) in its JSON. Orchestrator passes `--crop-live-bbox "x,y,w,h"` to `sb-compare-visual`. (Generalization extends to: `sb-extract-assets` could filter `imgUrls` to bbox before downloading; `sb-review-checks` could limit geometric rules to scope.)
+- **detector:** smoke metric — section builds must report diff% reflecting fidelity, not scope mismatch. 5 new tests in `test-compare-visual.mjs` cover crop parsing, dpr=1, dpr=3 multiplication, clamp, bbox-outside-screenshot, null path.
+- **origin:** smoke test `/build-page example-store.com` (2026-05-04)
+
+## #27 — Symmetric crop in the comparator
+
+- **id:** #27
+- **name:** Crop both live AND build, not just one side
+- **applies-to:** sb-compare-visual, orchestrator
+- **applies-when:** after #26, ~27pp of phantom diff still came from the build screenshot containing whitespace below the section (validate-render captures full viewport 390×844 but the section is 390×507 → the 337 CSS-px below pads against the cropped live).
+- **symptom:** asymmetric crop fixed live but left the build untrimmed → bottom whitespace of build screenshot vs corresponding region of cropped live → diff inflated by another bucket of phantom pixels.
+- **fix-recipe:** add `--crop-build-bbox` flag to `sb-compare-visual` paralleling `--crop-live-bbox`. Extract `applyCrop()` helper to share logic between the two sides. Orchestrator (`build-page` Step 5) passes `render.geometry.sections[0].bbox` when `viewportOverflow === false` AND the section is meaningfully smaller than the viewport. Smoke example-store: 62.32% (live-only crop) → 35.72% (both crops). Δ -26.6pp.
+- **detector:** 8 new tests in `test-compare-visual.mjs` (now 30 total) cover dual-crop math, clamp, bbox-outside-screenshot, null-path on each side independently.
+- **origin:** smoke test `/build-page example-store.com` (2026-05-04). **Insight:** when fixing one side of a symmetric operation, audit the other side immediately — anti-pattern #10 was simpler than it looked.
+
+## #28 — `review-checks` as ground truth for escalation
+
+- **id:** #28
+- **name:** Decision matrix replaces diff%-threshold heuristic
+- **applies-to:** orchestrator (`/build-page`, `/build-site`, `/clip-section`)
+- **applies-when:** orchestrator decides whether to (a) deliver, (b) loop with `fixHints`, (c) escalate to user. The legacy "diff>50 → catastrophic, skip auto-correct" heuristic mis-fired whenever the build was structurally clean but the diff came from scope mismatch or genuine visual drift.
+- **symptom:** clean builds with high diff% were sent into infinite auto-correct loops generating no-op fix attempts; broken builds with low diff% (e.g. coincidental near-match) were delivered without flagging the structural defect.
+- **fix-recipe:** remove the diff-threshold heuristic. Replace with a 2×2 decision matrix on `review.passed` × `compare.passed`:
+  - true × true → ✅ deliver
+  - false × true → ⚠️ escalate with warning (structural audit)
+  - true × false → ⚠️ escalate (visual drift, no actionable fix)
+  - false × false → 🔄 loop with `fixHints` (until `auto_correct_max`)
+
+  `sb-review-checks` runs **always**, not only inside the loop — it's pure deterministic (cheerio + regex, no chromium, ~0s overhead). Compare-visual measures *visual drift*; review-checks measures *structural soundness*; they are orthogonal.
+- **detector:** smoke example-store — review.passed=true × compare.passed=false routed to ⚠️ escalate (no infinite loop). Sanity test: deliberately-bugged build with `100vh` triggers anti-pattern #1 with `severity: high` and a specific `candidateFix`.
+- **origin:** smoke test `/build-page example-store.com` (2026-05-04)
+
+## #29 — Prettier preserving Liquid schema JSON
+
+- **id:** #29
+- **name:** Schema extraction → format → reinject around prettier
+- **applies-to:** sb-build-shopify
+- **applies-when:** the `write` subcommand runs `prettier.format(content, { parser: 'html' })` on a Liquid file containing `{% schema %}...{% endschema %}` with long-string defaults.
+- **symptom:** prettier in HTML mode word-wraps long lines unaware of Liquid blocks, inserting `\n` literally inside JSON strings (e.g. `"Revolutionizing Hair Care With Micro\nInfusion."`). Schema becomes invalid JSON; theme silently fails to register the section.
+- **fix-recipe:** in `sb-build-shopify/scripts/build-shopify.mjs`, modify `tryPrettierFormat` to: (1) extract `{% schema %}...{% endschema %}` BEFORE prettier; (2) substitute with `<!--sb-shopify-schema-placeholder-->`; (3) prettier the rest (HTML + Liquid tags-as-text); (4) format the schema content separately via `JSON.stringify(JSON.parse(rawJson), null, 2)`; (5) reinject in place of the placeholder. Defensive fallback: if the placeholder is dropped/mangled, return unformatted with `reason: 'prettier-placeholder-lost'` rather than losing the schema.
+- **detector:** new test in `test-build-shopify.mjs` — `write: schema with long-string default round-trips as parseable JSON` injects 100+ char default, write+validate end-to-end, asserts the string survives verbatim. Generalizable: any skill formatting a multi-language output (HTML+Liquid+JSON, MDX, JSX) does formatter passes via placeholder substitution.
+- **origin:** smoke E2E `sb-build-shopify` example-store.com (2026-05-04)
+
+## #30 — `liquidjs` Shopify-tag normalization
+
+- **id:** #30
+- **name:** Pre-process Shopify-native tags before liquidjs parse
+- **applies-to:** sb-validate-render
+- **applies-when:** rendering a Shopify section file with `preset=shopify-section`. `liquidjs` vanilla doesn't know `{% style %}`, `{% javascript %}`, `{% stylesheet %}` (Shopify-native runtime extensions) and throws `ParseError: tag "style" not found`.
+- **symptom:** render path crashes 100% on Shopify builds; smoke dies before generating screenshot; entire `/build-page --target shopify` flow blocked.
+- **fix-recipe:** in `validate-render.mjs` (~line 230–244), normalize Shopify-native tags to HTML wrappers BEFORE `engine.parseAndRender()` — `{% style %}` → `<style>`, `{% endstyle %}` → `</style>`, `{% javascript %}` → `<script>`, `{% endjavascript %}` → `</script>`, idem `{% stylesheet %}`. Inner Liquid (`{{ ... }}`, `{% if %}`) is preserved and still evaluates.
+- **detector:** smoke E2E pipeline must reach screenshot generation on a Shopify build. Backfill Shopify-render unit tests when `tmp/sb-validate-render-deps` scratch dir is set up. Generalizes (Pattern #13): when consuming a platform DSL with custom tags, normalize tags via a shim, not just filters.
+- **origin:** smoke E2E `sb-build-shopify` example-store.com (2026-05-04)
+
+## #31 — Hero fallback path strategy (base64 SVG placeholder)
+
+- **id:** #31
+- **name:** Replace dev-filesystem fallback with inlined base64 SVG
+- **applies-to:** sb-build-shopify (rules), anti-patterns memory
+- **applies-when:** any `image_picker` `{% else %}` branch in a Shopify section (hero, content image, logo, etc).
+- **symptom:** prior rules emitted `url('/Users/<dev>/.../assets/8a10....jpg')` literal in the fallback. Two-front breakage: (a) `sb-validate-render` couldn't resolve absolute paths without `file://` document base → build screenshot showed black rectangle, ~30pp of the 37.90% diff came from that; (b) merchant install was completely broken — the path is meaningless on any other machine.
+- **fix-recipe:** rewrite `references/shopify-build-rules.md` in 4+ places to drop `localPath` from fallbacks and use a 208-byte canonical base64 SVG placeholder (1170×900, fill `#d4d4d4`) for `image_picker` `{% else %}` branches. Update: (1) "What to lift into settings" table; (2) "Schema settings — `image_picker`" with the data URI literal + two examples (`<img>` and `{% style %}` background); (3) "Hero rules" `{% if %}{% else %}`; (4) "Output skeleton"; (5) "Responsive images"; (6) add anti-pattern #16 codifying the rule across all targets. The SVG works in any environment without path dependency.
+- **detector:** anti-pattern #16 detector in `sb-review-checks` (regex for `/Users/`, `/home/`, `/opt/`, `[A-Z]:\\Users\\`, etc.) catches future regressions. Smoke metric: re-run `/build-page example-store.com --target shopify` should drop diff from 37.90% toward <10% (pending — see also #32).
+- **origin:** smoke E2E `sb-build-shopify` example-store.com (2026-05-04)
+
+## #32 — `sb-validate-render` `--assets-map-path` for Shopify mock context
+
+- **id:** #32
+- **name:** Populate `image_picker` mock settings from the assets map
+- **applies-to:** sb-validate-render, orchestrator
+- **applies-when:** validating a Shopify section that uses `image_picker` settings without `default` (per anti-pattern #11) and a base64 SVG fallback (per #16/#31). The validate-render mock context didn't populate the setting, so the Liquid `{% else %}` branch fired → comparison was placeholder-vs-real-photo.
+- **symptom:** smoke E2E post-#29/#31 reported diff 75.30% (worse than 37.90% pre-fix). `tokenDiff=0`, `structuredDiffs=0`, `review.passed=true` — build structurally perfect; matrix routed to ⚠️ escalate (Pattern #28 working). Average-color analysis confirmed: live RGB(62,51,53) (real photo with overlay), build RGB(139,139,139) (placeholder SVG). Not a regression — limit of validate-render's Shopify path.
+- **fix-recipe:** (a) add optional flag `--assets-map-path <path>` to `sb-validate-render`; when present AND `preset=shopify-section`, `findAssetForImagePicker(settingId, assetsMap)` maps setting id → keyword → context substring (e.g. `hero|banner|cover` → matches `hero` / `ai-hero` / `banner` / `cover`; `logo|brand` → `header` / `ai-hdr` / `logo` / `brand`; `product|gallery|featured` → `ai-fp__gallery` / `product` / `gallery` / `featured`; fallback: first asset with non-empty context). (b) Read the matched asset via `readAssetAsDataUrl()` and populate the mock-context setting as `data:image/jpeg;base64,...`. (c) Liquid `image_url` filter shim returns the data-URL verbatim → `{% if section.settings.hero_image %}` resolves truthy → real branch active. (d) Output JSON gains `mockContext: { populated: [...], skipped: [...] }`. (e) Update orchestrator: `/build-page` Step 4 and `/build-site` Step 4f pass `--assets-map-path` when `target === shopify` and Step 2 produced an `assetsMap`. Graceful fallback when flag absent OR asset not found → original placeholder branch preserved.
+- **detector:** 8 new tests in `test-validate-render.mjs` cover id-keyword × context-keyword heuristics, fallback, empty-map, edge cases, and `--help` exposure (now 20 total, was 9). Smoke metric: example-store Shopify diff should drop 75.30% → ~8% (first <10% threshold validation).
+- **origin:** smoke E2E follow-up (2026-05-05)
+
+---
+
+## Maintenance
+
+- New IDs append sequentially (`#33`, `#34`, ...). Numbering is stable and additive — never renumber.
+- When a fix is superseded by upstream tooling improvements (e.g. liquidjs ships native `{% style %}` support → #30 obsolete), keep the entry but add `superseded-by:` rather than deleting; the historical context is the value.
+- Cross-skill fixes (those touching ≥2 skills) need entries in BOTH skills' code commentary referencing the ID — `// see fixes.md #27 for why this crops both sides`. Maintainers grepping for the ID find the recipe immediately.