@zohofinance/commerce 1.0.0 → 1.1.0

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/dev-server-and-urls.md

@@ -0,0 +1,136 @@
+# Dev server + page URLs — ask before you browse
+
+**Read this before any Chrome DevTools MCP `navigate_page` call during `/build-theme`.**
+
+URL paths vary by store and dev setup. **Never assume** `/` is home or `/collections/all` is the collection page.
+
+---
+
+## Step 1 — Collect `storeUrl` from the developer (mandatory)
+
+Before starting or requesting the dev server, ask:
+
+> What is your **storeUrl** for local dev?
+> Example: `<your store url>`
+
+Record it in scratchpad:
+
+```json
+// .claude/scratchpad/<theme>/dev-config.json
+{
+  "store_url": "<your store url>",
+  "dev_server_port": 3000,
+  "page_urls": {},
+  "confirmed_by_developer": false
+}
+```
+
+Do not hardcode a demo store URL unless the developer confirms it.
+
+---
+
+## Step 2 — Dev server (ask or start)
+
+Pass the developer's store URL into `theme dev` via `--storeUrl`. Without it, the preview uses mock data only.
+
+Use the value from Step 1 (`dev-config.json` → `store_url`) as `<your store url>`.
+
+**Option A — Developer starts it (preferred if already running):**
+
+```bash
+cd <theme_name>
+npx @zohofinance/commerce theme dev --storeUrl=<your store url>
+```
+
+Ask: *"Is the dev server already running on port 3000? If not, please start it with the command above (or tell me to start it)."*
+
+**Option B — Agent starts it:**
+
+1. Check: `lsof -i :3000`
+2. If not running, start in background from the theme folder:
+
+```bash
+npx @zohofinance/commerce theme dev --storeUrl=<your store url>
+```
+
+3. Wait for "Preview theme in http://localhost:3000" (up to 30s)
+4. Tell the developer: *"Dev server started with your storeUrl."*
+
+If the server fails to start → stop and ask the developer to fix CLI/network issues. Do not proceed to visual verify.
+
+---
+
+## Step 3 — Confirm page URLs with the developer (mandatory before browse)
+
+Present the URLs you plan to use and **wait for confirmation** (or correction):
+
+| Page | Default guess (verify!) | Example confirmed |
+|---|---|---|
+| Home | `http://localhost:3000/home` | `http://localhost:3000/home` |
+| Product | `http://localhost:3000/products/<handle>` | `http://localhost:3000/products/item-1` |
+| Collection | `http://localhost:3000/collections/<handle>` | `http://localhost:3000/collections/all-products` |
+| Blog list | `http://localhost:3000/blogs` or `/blog` | ask developer |
+| Blog detail | `http://localhost:3000/blogs/<handle>` | ask developer |
+
+**Ask once per build** (main orchestrator), not per subagent:
+
+```
+Before I run visual verify in the browser, please confirm these page URLs:
+
+  Home:       http://localhost:3000/home
+  Product:    http://localhost:3000/products/item-1
+  Collection: http://localhost:3000/collections/all-products
+  Blog list:  ?
+  Blog detail: ?
+
+Reply with corrections or YES to proceed.
+```
+
+After confirmation, write to `dev-config.json`:
+
+```json
+{
+  "page_urls": {
+    "index": "http://localhost:3000/home",
+    "product": "http://localhost:3000/products/item-1",
+    "collection": "http://localhost:3000/collections/all-products"
+  },
+  "confirmed_by_developer": true,
+  "confirmed_at": "<ISO8601>"
+}
+```
+
+**Subagents and section builders MUST read `dev-config.json`** — they do not guess URLs.
+
+---
+
+## Step 4 — Navigate only after confirmation
+
+```
+✅ dev-config.json exists AND confirmed_by_developer === true
+✅ dev server responding on localhost:3000
+→ navigate_page to the confirmed URL for that page
+```
+
+If `confirmed_by_developer` is false → **do not open the browser**. Ask the main orchestrator to collect URLs from the developer.
+
+---
+
+## Common mistakes
+
+| Wrong | Right |
+|---|---|
+| `http://localhost:3000/` for home | `http://localhost:3000/home` (after developer confirms) |
+| `/product/sample-product` | `/products/item-1` (handle varies by store) |
+| `/collections/all` | `/collections/all-products` (handle varies) |
+| Hardcoded demo storeUrl | Value from developer in `dev-config.json` |
+
+---
+
+## Who asks what
+
+| Role | Responsibility |
+|---|---|
+| **Main orchestrator** | Collect `storeUrl` + confirm all page URLs once at Stage 0/1 |
+| **Page orchestrator** | Read `dev-config.json`; never invent URLs |
+| **Section subagent** | Read `dev-config.json`; if missing, write `needs-developer.md` and escalate |

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/exemplars.md

@@ -0,0 +1,79 @@
+# LOGIC patterns — build from docs (no sibling themes available)
+
+When a page agent builds a section, it does NOT pick one exemplar file and stay close to it. It **reads the official ZCommerce docs**, synthesizes the required logic patterns, then writes **fresh code** for the new theme.
+
+There is no anchor. There is no sibling theme to reference. There is only doc-based pattern synthesis → fresh write.
+
+## Why docs, not sibling themes
+
+No sibling themes are available in this standalone setup. Every section must be built from the official ZCommerce documentation:
+
+- `zcommerce-docs/sections.md` — section structure, schema rules, block patterns.
+- `zcommerce-docs/reference/schema-types.md` — all valid schema field types.
+- `zcommerce-docs/snippets.md` — snippet variable scoping.
+- `zcommerce-docs/reference/filters.md` and `tags.md` — valid Liquid primitives.
+
+The output is a clean, fresh implementation that follows the documented patterns without copying from any existing source.
+
+## The protocol
+
+For each section archetype the agent needs to build:
+
+1. **Read the docs.** Consult `zcommerce-docs/sections.md` and `zcommerce-docs/reference/schema-types.md` for the required structure.
+2. **Plan the schema.** Identify which schema field types (text, richtext, image_picker, url, etc.) are appropriate for each visible element.
+3. **Identify patterns.** From the docs, determine:
+   - Schema field types and IDs to use
+   - Liquid loop and conditional patterns
+   - Web component usage (`<add-to-cart>`, `<expand-accordion>`, etc.)
+   - Edge case handling (empty states, missing data, accessibility hooks)
+4. **Plan fresh code.** Sketch the new section's DOM + schema using the documented patterns AND design values (Tailwind classes, colors, fonts, spacing) from the Figma + theme tokens.
+5. **Write fresh.** No `cp` commands. No copy-paste of multi-line blocks. The agent types the new file.
+6. **Lint.** `verify-theme.mjs` will catch structural problems. If the lint fails, fix and re-run.
+
+## Archetype → how to build
+
+For each archetype below, build from the ZCommerce docs. No sibling themes are available.
+
+| Archetype | How to build |
+|---|---|
+| Hero banner | build from docs (zcommerce-docs/sections.md) — no sibling themes available |
+| Multi-image hero | build from docs (zcommerce-docs/sections.md) — no sibling themes available |
+| Promo banner / advertisement strip | build from docs (zcommerce-docs/sections.md) — no sibling themes available |
+| Product collection / listing grid | build from docs (zcommerce-docs/sections.md) — no sibling themes available |
+| Product card snippet | build from docs (zcommerce-docs/snippets.md) — no sibling themes available |
+| Product detail page (PDP) | build from docs (zcommerce-docs/sections.md) — no sibling themes available |
+| Variant picker | build from docs (zcommerce-docs/snippets.md) — no sibling themes available |
+| Cart list | build from docs (zcommerce-docs/sections.md) — no sibling themes available |
+| Cart popup / mini-cart | build from docs (zcommerce-docs/sections.md, zcommerce-docs/snippets.md) — no sibling themes available |
+| Checkout | build from docs (zcommerce-docs/sections.md) — no sibling themes available |
+| Account: profile / address / order / order-status | build from docs (zcommerce-docs/sections.md) — no sibling themes available |
+| Account: quote (B2B) | build from docs (zcommerce-docs/sections.md) — no sibling themes available |
+| CTA cards / promo grid | build from docs (zcommerce-docs/sections.md) — no sibling themes available |
+| Blog list / blog grid | build from docs (zcommerce-docs/sections.md) — no sibling themes available |
+| Blog detail / article | build from docs (zcommerce-docs/sections.md) — no sibling themes available |
+| Category header | build from docs (zcommerce-docs/sections.md) — no sibling themes available |
+| Filter rail | build from docs (zcommerce-docs/sections.md) — no sibling themes available |
+| Pagination snippet | build from docs (zcommerce-docs/snippets.md) — no sibling themes available |
+| 404 | build from docs (zcommerce-docs/sections.md) — no sibling themes available |
+| Sign-in / sign-up / forgot-password | build from docs (zcommerce-docs/sections.md) — no sibling themes available |
+| Generic page | build from docs (zcommerce-docs/sections.md) — no sibling themes available |
+
+If no doc covers the archetype, build from the schema-types docs + best-practices docs (no inherited logic).
+
+## Anti-exemplars — patterns to avoid
+
+These code-quality failures must be avoided when writing new sections:
+
+- Hero-banner sections exceeding 600 lines (deeply nested conditionals)
+- Collection-grid sections exceeding 900 lines (6-level nesting)
+- Product-details sections exceeding 1600 lines (longest in any repo)
+- Header sections exceeding 500 lines (megamenu permutation bloat)
+- Product-card snippets exceeding 250 lines (B2B-specific logic not stripped for B2C)
+
+If the agent's planned section starts looking like these in line count or nesting depth, re-plan by simplifying the structure.
+
+## Hard rule
+
+The agent must build each archetype fresh from the official docs (`zcommerce-docs/sections.md`, `zcommerce-docs/snippets.md`). No sibling themes are available to read from.
+
+The lint and `verify-theme.mjs` catch structural problems. Build from docs to write cleanly.

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/figma-discovery.md

@@ -0,0 +1,138 @@
+# Figma discovery — auto-find pages (do NOT ask for URLs first)
+
+When the developer runs `/build-theme <theme> <figma_file_key>`, the agent **discovers pages itself**. Asking for per-page Figma URLs is a **fallback only**.
+
+---
+
+## What the developer provides
+
+```
+/build-theme my_theme <figma_file_key>
+```
+
+Optional: root canvas node ID (e.g. `<root_node_id>` for the theme canvas).
+
+**They do NOT need to paste 5 page URLs** if the file follows the standard Commerce Theme layout.
+
+---
+
+## Why selecting one frame is not enough
+
+Selecting a single frame in Figma (e.g. Product Detail Page) gives MCP context for **that node only**. It does not expose:
+
+- The full **Website View** / **Mobile View** trees
+- Sibling pages (index, collection, blogs, …)
+- The **Guidelines** frame for tokens
+
+The agent must **walk up** to the theme canvas and call `get_metadata` / `get_design_context` on the root — not treat the selected frame as the only input.
+
+---
+
+## Discovery protocol (Phase 0 — mandatory before asking developer)
+
+### Step 1 — Resolve file key and root node
+
+From command args or the developer's Figma URL:
+
+- `fileKey`: e.g. `<figma_file_key>`
+- `rootNodeId`: optional; if omitted, call `get_metadata` on the file canvas and find the theme canvas (e.g. the named theme frame)
+
+### Step 2 — Fetch structure
+
+```
+Figma MCP: get_metadata
+  fileKey: <fileKey>
+  nodeId:  <rootNodeId or canvas id>
+
+Figma MCP: get_design_context  (if metadata is sparse)
+  fileKey: <fileKey>
+  nodeId:  <Website View frame id>
+```
+
+Look for these top-level children under the theme canvas:
+
+| Frame name (typical) | Contains |
+|---|---|
+| Guidelines | Tokens — fonts, colors, components |
+| Website View | Desktop page frames (~1496px wide) |
+| Mobile View | Mobile page frames (~390px wide) |
+
+### Step 3 — Build page map
+
+For each direct child of **Website View**, record name + node ID. Match to **Mobile View** by page name:
+
+```
+PAGE MAP (auto-discovered)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Page Name             | Desktop Node | Mobile Node  | Page JSON
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Home Page             | 2613:146     | 2375:4029    | index.json
+Product Detail Page   | 2321:4829    | 2560:1012    | product.json
+...
+```
+
+Map names → standard JSON filenames:
+
+| Figma name contains | JSON file |
+|---|---|
+| Home, Index | `index.json` |
+| Product | `product.json` |
+| Collection, Listing, Category | `collection.json` |
+| Blog Page, Blog List | `blogs.json` |
+| Blog Detail, Article | `blog.json` |
+
+### Step 4 — Present map to developer (approval gate)
+
+Show the discovered map. Ask:
+
+> I found these pages in Figma. Does this look correct? Reply YES / EDIT / SKIP.
+
+**Do not ask for Figma URLs** if discovery succeeded.
+
+### Step 5 — Save artefacts
+
+```
+.claude/scratchpad/<theme>/figma-discovery.json
+.claude/scratchpad/<theme>/bootstrap/guidelines-extraction.md
+```
+
+```json
+{
+  "file_key": "<figma_file_key>",
+  "root_node_id": "2193:766",
+  "pages": {
+    "index": { "desktop": "2613:146", "mobile": "2375:4029" },
+    "product": { "desktop": "2321:4829", "mobile": "2560:1012" }
+  },
+  "discovered_at": "<ISO8601>",
+  "source": "get_metadata"
+}
+```
+
+Page orchestrators read node IDs from this file — not from developer-pasted URLs.
+
+---
+
+## When to ask the developer for URLs (fallback only)
+
+| Condition | Action |
+|---|---|
+| `get_metadata` / `get_design_context` fails | Ask for file URL + root node, or open Figma desktop |
+| No "Website View" / "Mobile View" in file | Ask which frames are desktop/mobile for each page |
+| Ambiguous duplicate page names | Ask which frame is canonical |
+| Developer passed **only** a single-page URL (not full build) | Scope to that page; don't ask for other 4 pages |
+| File is non-standard (no guidelines frame) | Ask for guidelines URL OR use `get_variable_defs` |
+
+**Never ask for all 5 page URLs when `figma_file_key` was provided and discovery returned a valid map.**
+
+---
+
+## Selected frame in Figma desktop
+
+If the developer selected a frame before running the command:
+
+1. Use that node's `fileKey` + `nodeId` as a **hint** (which page they're focused on)
+2. Still run discovery from the **parent theme canvas** to find all pages
+3. Do not assume the selected frame is the only page to build
+
+Example: selected `2321:4829` (Product) → discovery finds it's under Website View → also find index, collection, blogs from siblings.

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/figma-extraction.md

@@ -0,0 +1,132 @@
+# Per-element Figma extraction — the ONLY source of truth for visual values
+
+The previous skill versions failed because agents generated section code from imagination (look at a screenshot, guess values, write code). This document fixes that. Every section file MUST be built from a **Figma Spec** — a structured JSON of every visible element's exact properties, extracted from `get_design_context` on the section's specific Figma node. No more guessing.
+
+## Rule
+
+Before writing a single line of section markup, the section-builder subagent MUST produce a Figma Spec at `<scratchpad>/sections/<section>/figma-spec.json`. The build phase reads this JSON and transcribes — it does NOT look at a screenshot and improvise.
+
+The `verify-theme.mjs` `figma_spec_present` check fails the build if any non-common section is missing its `figma-spec.json`.
+
+## Step 1 — Identify the section's Figma node
+
+The page orchestrator gave you a node ID. If it didn't, ASK THE DEVELOPER (see `ask-developer.md`):
+
+> "I need to build the {section_name} section but I don't have its Figma node ID. Can you give me the Figma URL with `?node-id=X-Y` pointing at this section's frame?"
+
+Never proceed past this step without a confirmed node ID.
+
+## Step 2 — Get the structured tree (SECTION NODE ONLY — Level B)
+
+```
+Figma MCP: get_design_context
+  fileKey: <from discovery>
+  nodeId:  <the SECTION's node ID from Level A sections.plan.md>
+```
+
+**Never** pass the parent page frame node ID here. Level B agents that read the full page hallucinate styles from unrelated sections.
+
+For each element, explicitly extract:
+- `border_radius` — if 0 or missing, code must have **no** border-radius
+- `background` / text `color` — exact hex before token mapping
+- Image frames — `w`, `h`, `object_fit` for product card media boxes
+
+Save raw response to `<scratchpad>/sections/<section>/design-context.raw.json`.
+
+If `get_design_context` returns "nothing selected" or fails, fall back: `get_metadata` to walk children, then `get_screenshot` on each leaf — but **ask the developer to open Figma desktop and select the section** as the preferred recovery path.
+
+## Step 3 — Walk the tree and build the Figma Spec
+
+For every visible element, extract:
+
+```json
+{
+  "id": "stable identifier within the section, e.g. 'hero-left-panel-image'",
+  "kind": "frame | text | image | vector | line | rectangle",
+  "position": { "x": 64, "y": 80, "w": 480, "h": 640 },
+  "layout": {
+    "type": "flex | grid | absolute",
+    "direction": "row | column",
+    "gap": 16,
+    "padding": { "top": 32, "right": 32, "bottom": 32, "left": 32 },
+    "align_items": "start | center | end | stretch",
+    "justify_content": "start | center | end | space-between"
+  },
+  "background": { "type": "solid | image | linear-gradient", "value": "#FFAB4A" },
+  "border": { "width": 1, "color": "#D1D1D1", "style": "solid" },
+  "border_radius": { "top_left": 24, "top_right": 24, "bottom_right": 24, "bottom_left": 24 },
+  "shadow": { "x": 0, "y": 4, "blur": 12, "spread": 0, "color": "rgba(0,0,0,0.08)" },
+
+  "text": {
+    "content": "Soft toys for your kiddo",
+    "font_family": "Oswald",
+    "font_weight": 600,
+    "font_size": 56,
+    "line_height": 56,
+    "letter_spacing": 0,
+    "color": "#000000",
+    "align": "left"
+  },
+
+  "image": {
+    "node_id": "2613:148",
+    "natural_w": 800,
+    "natural_h": 800,
+    "object_fit": "cover | contain",
+    "asset_filename_suggestion": "hero-banner-panel-left-penguin.png"
+  },
+
+  "children": [ ... recursive ... ]
+}
+```
+
+Every field is exact (not "roughly 56px" — 56). Every color is the exact hex from the Figma fill. Every position is the exact pixel coordinate. Children are recursive.
+
+For each top-level section, the Figma Spec is one root object containing the full hierarchy.
+
+## Step 4 — Map Figma colors → theme tokens
+
+For every color in the Figma Spec, look up the theme tokens in `settings/theme.json` and `figma-variables.json`. If a color exactly matches a token, replace the hex in the spec with the token name:
+
+```json
+"background": { "type": "solid", "value": "var(--color-primary)" }
+```
+
+If no token matches within ΔE 1.5, leave the hex AND flag in `<scratchpad>/sections/<section>/unmapped-colors.md` so the developer can decide whether to:
+- Add a new theme token, OR
+- Use the raw hex as a one-off (rare).
+
+Same for spacing: if a Figma padding of 64 matches `--space-16`, use `var(--space-16)`. Otherwise log it.
+
+Same for fonts: should always map to `--font-heading` or `--font-body`.
+
+## Step 5 — Extract image assets
+
+For every `image` node in the spec:
+
+1. Call `mcp__32a68a89-...__get_screenshot` on the image's `node_id` with `maxDimension: 1600` and `enableBase64Response: true`.
+2. Decode the base64 PNG and save it to `assets/<asset_filename_suggestion>` (the filename is auto-generated as `<section-name>-<purpose>.png`).
+3. Update `assets/fingerprint.json` to include the new asset.
+
+If `get_screenshot` returns an empty or non-PNG response, or if the sandbox can't decode it, ASK THE DEVELOPER:
+
+> "I extracted the hero-banner left-panel image (Figma node 2613:148) but the result wasn't usable. Can you export this image manually from Figma and drop it in `assets/hero-banner-panel-left-penguin.png`?"
+
+Once the developer confirms, continue.
+
+**Never substitute a sibling theme's asset.** Never copy assets from another theme's folder. If extraction fails and developer hasn't provided, write to NEEDS_REVIEW and use a 1×1 transparent placeholder so the section still renders.
+
+## Step 6 — Save the Figma Spec
+
+Save to `<scratchpad>/sections/<section>/figma-spec.json`. This is the build contract. The next phase (Liquid build) transcribes this directly.
+
+## Step 7 — Hand off to the build phase
+
+The build phase reads `figma-spec.json` and produces the Liquid file by transcription. Every element in the spec must appear in the markup. Every text content goes into the schema as a setting default (or the page JSON if it's block-instance content). Every measurement either becomes a Tailwind class (if a token matches) or inline CSS via `{% style %}`.
+
+## Key principles
+
+- **No imagination.** If the value isn't in the Figma Spec, don't put it in the code.
+- **No screenshot-only guesses.** Screenshots are for human visual diff after the build, not for measurement extraction during the build.
+- **Ask the developer** when extraction fails, when an asset can't be downloaded, when a Figma node isn't accessible, when a token doesn't match.
+- **Save everything** to scratchpad. The Figma Spec is auditable — if a build produces wrong output, the developer can diff the Spec against the rendered page and see exactly where the divergence happened.

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/image-sources.md

@@ -0,0 +1,84 @@
+# Image sources — dev server vs deploy
+
+One rule that causes visual mismatch when wrong: **how image `src` is built depends on where the URL comes from.**
+
+## Quick reference
+
+| Source | Stored as | Liquid pattern | Notes |
+|---|---|---|---|
+| Theme static asset (`assets/hero.png`) | filename in schema JSON | `{{ 'hero.png' \| asset_url }}` | Always use `asset_url` |
+| Schema `image_picker` default | `{ "url": "hero.png" }` | `{{ section.settings.image.url \| asset_url }}` | **Required in dev** — JSON stores filename only |
+| Schema `image_picker` admin upload | full CDN URL | `{{ section.settings.image.url }}` | Already absolute — do NOT pipe `asset_url` |
+| Product / collection media | CDN URL from API | `{{ image.url }}?organization_id={{ organizationId }}` | Live store data — not `asset_url` |
+| Figma-extracted decorative PNG | `assets/<section>-<role>.png` | `{{ '<file>.png' \| asset_url }}` | Saved during build |
+
+## The dev-server catch (most common visual bug)
+
+In the **local dev server**, page JSON and schema defaults store image values as **filenames** (e.g. `"hero-banner-left.png"`). The dev proxy does not resolve bare filenames — you must pipe through `asset_url`:
+
+```liquid
+{% comment %} ✅ Theme asset from schema JSON default {% endcomment %}
+<img
+  src="{{ section.settings.panel_image.url | asset_url }}"
+  alt="{{ section.settings.panel_image.alt | default: section.settings.heading | escape }}"
+  width="668"
+  height="400"
+  loading="lazy"
+>
+
+{% comment %} ✅ Theme asset with known filename {% endcomment %}
+<img src="{{ 'icon-heart.png' | asset_url }}" alt="" width="48" height="48">
+```
+
+```liquid
+{% comment %} ❌ Broken in dev — filename not resolved {% endcomment %}
+<img src="{{ section.settings.panel_image.url }}">
+
+{% comment %} ❌ Wrong filter — product CDN URL is not a theme asset {% endcomment %}
+<img src="{{ product.featured_image.url | asset_url }}">
+```
+
+When the theme is **packaged and deployed**, the platform may resolve some paths differently — but **always write `asset_url` for theme assets**. One pattern works in dev and production.
+
+## Safe image helper pattern
+
+Keep it simple — no extra abstractions:
+
+```liquid
+{% liquid
+  assign img_url = section.settings.image.url
+  if img_url != blank
+    unless img_url contains '://'
+      assign img_url = img_url | asset_url
+    endunless
+  endif
+%}
+{% if img_url != blank %}
+  <img src="{{ img_url }}" alt="{{ section.settings.image.alt | escape }}" width="400" height="300" loading="lazy">
+{% endif %}
+```
+
+Use this when a setting can be either a theme filename (dev/defaults) or a CDN URL (admin upload).
+
+## Product / collection images (PDP, cards, cart)
+
+```liquid
+<img
+  src="{{ image.url }}?organization_id={{ organizationId }}"
+  alt="{{ product.title | escape }}"
+  width="{{ image.width | default: 400 }}"
+  height="{{ image.height | default: 400 }}"
+  loading="lazy"
+>
+```
+
+Do not use `asset_url` for `product.images`, `product.media`, or `collection.image`.
+
+## Visual verify checklist for images
+
+During Chrome DevTools MCP visual compare, if Figma shows an image but the browser shows empty/broken:
+
+1. `list_network_requests` — look for 404 on image URLs
+2. Confirm `asset_url` is used for theme assets from JSON defaults
+3. Confirm file exists in `assets/`
+4. Confirm `pages/<page>.json` block settings reference the correct filename