@zohofinance/commerce 1.0.0 → 1.1.0

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

@@ -0,0 +1,227 @@
+# Verification — Chrome DevTools MCP first, simple gates
+
+Verification runs per-section, per-page, then theme-wide (Stage 2).
+
+## Primary gates (Chrome DevTools MCP — mandatory)
+
+| Gate | Tool | Pass |
+|---|---|---|
+| Visual | `take_screenshot` + Figma `get_screenshot` + vision diff | 0 CRITICAL in `visual-diff.md` |
+| A11y | `lighthouse_audit` navigation mobile | Score ≥ 90 |
+| Perf | `lighthouse_audit` mobile on page routes | Score ≥ 85 |
+| Images | `list_network_requests` | No 404 theme assets (use `asset_url` — `image-sources.md`) |
+| Lint | `lint-section.mjs` at write time | PASS |
+
+See `.cursor/skills/browser-verify.md` and `visual-verify-loop.md`.
+
+## Optional release scripts (CI only)
+
+`pixel-diff.mjs`, `a11y.mjs`, `perf.mjs` produce JSON artefacts for pipelines. **Do not skip MCP visual compare** because a script passed.
+
+## End-of-run metrics (mandatory)
+
+```bash
+node .claude/skills/theme-from-figma/scripts/record-build-metrics.mjs <theme>
+node .claude/skills/theme-from-figma/scripts/verify-theme.mjs <theme>
+```
+
+Append results to `.claude/scratchpad/<theme>/report.md`. See `build-metrics.md`.
+
+## Per-page gates (Phase 5 of `page-builder.md`)
+
+All four gates run for every page. The puppeteer scripts in `scripts/` are the official source of pass/fail.
+
+**Non-negotiable.** Verification is the only thing standing between a built theme and a shipped theme that doesn't match the input. In real-world use, agents have skipped verification (returning "passed" without actually invoking the scripts) and shipped output that was structurally identical to the base theme — that's the failure mode that bit a prior build. Each agent's report MUST include the four JSON files produced by the scripts; the consolidator confirms their existence before accepting the page.
+
+### Gate 1 — Pixel diff (visual fidelity)
+
+Script: `scripts/pixel-diff.mjs`
+
+Inputs:
+- `--rendered-url` — the dev server URL.
+- `--figma-image` — the Figma frame screenshot saved during intake.
+- `--viewport` — `1440x900` for desktop, `375x812` for mobile.
+- `--out` — path to write the JSON report.
+
+The script:
+1. Launches headless Chrome at the viewport.
+2. Navigates to the rendered URL.
+3. Waits for `networkidle`.
+4. Screenshots the page (or section if a selector is given).
+5. Resizes the Figma reference image to match.
+6. Runs `pixelmatch` for a region-by-region ΔE diff.
+7. Outputs a JSON report with diff regions, max ΔE, mean ΔE, total mismatched pixel ratio.
+
+**Pass thresholds:**
+- Mean ΔE < 2.0
+- Max ΔE < 5.0 (no single region wildly off)
+- Mismatched pixel ratio < 3%
+
+If any threshold fails, the JSON lists the specific regions; the agent edits the responsible section and re-runs only this gate.
+
+### Gate 2 — Accessibility
+
+Script: `scripts/a11y.mjs`
+
+Inputs:
+- `--url` — the dev server URL.
+- `--selector` — optional, scope to a single section.
+- `--out` — path to write the JSON report.
+
+The script:
+1. Launches headless Chrome.
+2. Navigates to the URL.
+3. Injects axe-core (4.10).
+4. Runs `axe.run()` with WCAG 2.1 AA tags.
+5. Filters to `impact: critical` and `impact: serious` for the pass/fail decision; reports all impacts in the JSON.
+
+**Pass threshold:** zero critical, zero serious violations.
+
+Moderate violations are reported and surfaced in the agent's report but don't block the gate. The most common moderate is `color-contrast` — fix when easy, defer when the design intent demands a marginal ratio.
+
+### Gate 3 — Performance
+
+Script: `scripts/perf.mjs`
+
+Inputs:
+- `--url` — the dev server URL.
+- `--form-factor` — `mobile` (default) or `desktop`.
+- `--out` — path to write the JSON report.
+
+The script:
+1. Launches headless Chrome.
+2. Runs Lighthouse with the performance category only.
+3. Outputs JSON with score, LCP, FCP, CLS, TBT, Speed Index.
+
+**Pass thresholds (mobile, throttled):**
+- Performance score ≥ 90
+- LCP < 2.5s
+- CLS < 0.1
+- TBT < 200ms
+
+Desktop usually passes if mobile does, but the script runs both and reports both.
+
+### Gate 4 — Token / lint compliance
+
+This is `scripts/lint-section.mjs`, already run during Phase 4 build. Verification confirms every section file passed lint. If a file slipped through without lint, run it now.
+
+## Running multiple gates in parallel
+
+All three puppeteer scripts can run concurrently — they each launch their own Chrome instance. Use bash backgrounding:
+
+```bash
+node .../pixel-diff.mjs --rendered-url $URL --figma-image $D --viewport 1440x900 --out $OUT/pd-d.json &
+node .../pixel-diff.mjs --rendered-url $URL --figma-image $M --viewport 375x812  --out $OUT/pd-m.json &
+node .../a11y.mjs       --url $URL                                                --out $OUT/axe.json   &
+node .../perf.mjs       --url $URL --form-factor mobile                           --out $OUT/lh.json    &
+wait
+```
+
+This brings the verify phase down to ~30s wall-clock from ~2min serial.
+
+---
+
+## Stage 2 — Cross-theme consolidation
+
+After all five parallel page agents finish, a single coordinator agent does theme-wide checks:
+
+### 1. Token consistency
+
+For each token in `theme.json`, find every direct reference across the theme and confirm they all use the variable, not a hardcoded value. The lint script catches per-file hardcodes; this is the theme-wide assertion.
+
+```bash
+grep -rE '#[0-9a-fA-F]{6}\b' sections/ snippets/ \
+  | grep -v 'figma-variables.json' | grep -v '#section-'
+```
+
+Any results → manual review; usually means a section snuck a hardcoded color past the lint.
+
+### 2. Header / footer presence check
+
+The index agent built header and footer from the Figma. Confirm:
+- `sections/header.liquid` and `sections/footer.liquid` exist and are non-empty.
+
+```bash
+# Confirm header and footer exist and are non-empty
+test -s sections/header.liquid || { echo "FAIL: header.liquid missing or empty" >&2; exit 1; }
+test -s sections/footer.liquid || { echo "FAIL: footer.liquid missing or empty" >&2; exit 1; }
+```
+
+After the four parallel page agents finish, confirm `header.liquid` and `footer.liquid` are still identical to the snapshot the index agent took when it published the ready-marker:
+
+```bash
+diff sections/header.liquid .claude/scratchpad/<theme>/header.liquid.locked
+diff sections/footer.liquid .claude/scratchpad/<theme>/footer.liquid.locked
+```
+
+### 3. Navigation correctness
+
+Walk the rendered theme: dev server up, navigate `/home → /collections/all → /products/<sample> → /blog → /blog/<sample-post>`. Confirm:
+- Each transition works (no Liquid errors).
+- Header active state correct on each page.
+- Footer renders identically on each page.
+- Browser console has no critical errors.
+
+Quickest implementation: a single puppeteer script `scripts/nav-walk.mjs` (not implemented in v1; the agent can do it via Chrome DevTools MCP `navigate_page` + `list_console_messages`). See `.cursor/skills/browser-verify.md`.
+
+### 4. i18n key coverage
+
+```bash
+node .claude/skills/theme-from-figma/scripts/lint-i18n.mjs <theme>
+```
+(Optional v2; in v1, do a grep-based check: every `t:` key referenced must exist in `i18n/en.schema.json`.)
+
+### 5. Page JSON validity
+
+For each `pages/*.json`, validate against the schema of the sections it references. If a page wires `hero-banner` with field `unknownField`, the section schema won't have it and the page won't render — catch this now, not at first deploy.
+
+### 6. Final theme-wide perf run
+
+Run `scripts/perf.mjs` against each top-level page route. The per-page agent ran it earlier; this is the final cross-check to confirm no regression from cross-page wiring (header/footer JS loaded on every page might pull down product page perf).
+
+### 7. Produce the consolidated report
+
+```
+THEME: lush_market — BUILD COMPLETE
+Time: 6m12s (bootstrap 28s + parallel pages 4m48s + consolidation 56s)
+
+PAGES BUILT:
+  index        5 sections   all gates pass     1 iteration
+  listing      4 sections   all gates pass     1 iteration
+  product      7 sections   all gates pass     2 iterations  (a11y contrast fix)
+  blog_list    3 sections   all gates pass     1 iteration
+  blog_detail  2 sections   all gates pass     1 iteration
+
+LINT METRICS (aggregate):
+  Total .liquid files written: 21
+  Avg lines per section: 124
+  Avg max DOM depth: 4.8
+  Avg max classes/element: 9
+  Lint failures during build: 4 (all fixed, 0 outstanding)
+
+GATES (theme-wide):
+  pixel-diff:   pass on 5/5 pages (mean ΔE 1.4, max 4.2)
+  a11y:         pass on 5/5 pages (0 critical, 0 serious; 3 moderate)
+  perf:         pass on 5/5 pages (avg score 93)
+  token cons.:  pass (0 hardcoded values)
+  nav:          pass (5 routes walked, 0 errors)
+
+NEEDS_REVIEW (3):
+  - hero-banner: figma font weight 850, used 800 (closest available)
+  - product-options: 1 moderate axe violation — color-contrast 4.3:1 on disabled state
+  - blog-detail: long-form content typography uses scoped classes (correct), but
+    the prose styles might benefit from a `prose` plugin sweep
+
+NEXT:
+  - Theme is ready at lush_market/
+  - Review NEEDS_REVIEW items above
+  - When approved: cd lush_market && yarn create-theme to package
+```
+
+## When verification fails after 3 iterations
+
+A parallel page agent that exhausts its iteration budget writes `NEEDS_REVIEW` to its report and exits. The coordinator surfaces these to the developer with the specific gate output and the relevant section file path. The developer either:
+
+1. Approves the deviation (theme ships with caveats noted in the report).
+2. Asks the coordinator to spawn one more focused fix agent on a specific section.
+3. Adjusts the input (e.g. updates the Figma file) and re-runs the affected page only.

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/visual-verify-loop.md

@@ -0,0 +1,117 @@
+# Visual verify loop — Chrome DevTools MCP (mandatory)
+
+**Goal:** rendered output must match Figma. No section ships without a structured visual diff showing **0 CRITICAL** items.
+
+**Canonical workflow:** `.cursor/skills/browser-verify.md`  
+**Image bugs:** `.claude/skills/theme-from-figma/image-sources.md`
+
+Puppeteer scripts (`pixel-diff.mjs`, etc.) are optional release artefacts — **Chrome DevTools MCP is the dev-loop source of truth.**
+
+---
+
+## The 3-gate verify (per section AND per page)
+
+Run all three gates. Keep it simple — no extra scripts unless MCP is unavailable.
+
+| Gate | Chrome DevTools MCP | Pass criteria |
+|---|---|---|
+| **Visual** | `take_screenshot` + Figma `get_screenshot` + agent vision diff | 0 CRITICAL mismatches |
+| **A11y** | `lighthouse_audit` mode `navigation` device `mobile` | Accessibility score ≥ 90, 0 critical axe issues in report |
+| **Perf** | `lighthouse_audit` on page route OR `performance_start_trace` if LCP suspect | Mobile perf ≥ 85 on pages; sections inherit page score |
+
+Also always run:
+- `list_console_messages` types `["error","issue"]` — fix section-related errors
+- `list_network_requests` — catch 404 images (usually missing `asset_url`)
+
+---
+
+## Per-section loop (section-builder subagent)
+
+### 1. Preconditions
+- `dev-config.json` exists with `confirmed_by_developer: true` — see `dev-server-and-urls.md`
+- Dev server running with developer's `storeUrl`: `npx @zohofinance/commerce theme dev --storeUrl=<your store url>` (ask them to start, or start and notify; value from `dev-config.json`)
+- Chrome DevTools MCP connected
+- Figma node ID in `figma-spec.json`
+- **Do not `navigate_page` until page URLs are confirmed with the developer**
+
+### 2. Capture (desktop + mobile)
+
+```
+list_pages → select_page (or new_page + pageId for parallel agents)
+emulate → 1440x900
+navigate_page → URL from dev-config.json page_urls (e.g. /home, /products/item-1)
+evaluate_script → scroll #section-<id> into view
+take_screenshot → scratchpad/.../rendered-desktop.png
+list_console_messages → errors/issues
+list_network_requests → 404 on images?
+```
+
+Repeat with `emulate → 375x812,mobile,touch` → `rendered-mobile.png`.
+
+**Parallel:** Figma `get_screenshot` desktop + mobile node IDs while browser captures.
+
+### 3. Compare in vision
+
+Write `visual-diff.md`:
+
+```markdown
+# Visual diff — <section>
+Desktop: 1440×900 | Mobile: 375×812
+
+## CRITICAL (must fix)
+1. [IMAGE] Left panel hero image missing — 404 on `hero-left.png` without asset_url
+   Fix: `{{ section.settings.image.url | asset_url }}`
+
+## MINOR
+(none)
+
+## SUGGESTION
+(none)
+
+Console errors: 0
+Network 404s: 1 (hero-left.png)
+```
+
+### 4. Fix CRITICAL only, re-loop
+
+Max **3 iterations** per section (was 5 — keep it simple). After 3, write `needs-developer.md` and exit.
+
+### 5. Section PASS criteria
+
+- `visual-diff.md` exists
+- 0 CRITICAL items
+- No console errors affecting this section
+- No 404 theme assets
+
+---
+
+## Per-page loop (page orchestrator, after assembly)
+
+Same 3 gates on the **whole assembled page**:
+
+1. Screenshot full page desktop + mobile (scroll segments if taller than viewport)
+2. Figma full-page screenshot (`2613:146` etc.)
+3. Vision diff focused on **inter-section** issues: spacing, order, missing/extra sections
+4. `lighthouse_audit` navigation mobile on page URL
+5. Save to `pages/<page>/visual-diff.md` + `pages/<page>/verify/lighthouse.json` if MCP returns path
+
+Max **2 page-level iterations**.
+
+---
+
+## What good output looks like
+
+```
+pages/product/sections/product-details/visual-diff.md  → 0 CRITICAL
+pages/product/visual-diff.md                         → 0 CRITICAL
+pages/product/verify/lighthouse-mobile.json          → a11y ≥ 90, perf ≥ 85
+```
+
+---
+
+## Never do
+
+- Skip visual verify and claim PASS
+- Write "looks good" without structured diff
+- Use puppeteer-only results when Chrome DevTools MCP is available
+- Forget `asset_url` for schema JSON image defaults (top cause of missing images in dev)

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/_index.md

@@ -0,0 +1,4 @@
+---
+title: "Documentation"
+weight: -1
+---

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/assets.md

@@ -0,0 +1,105 @@
+---
+title: "Assets"
+weight: 8
+---
+
+# Assets
+
+Assets are static files — CSS, JavaScript, images, and fonts — stored in the `assets/` folder.
+
+## Linking Assets
+
+Use the `asset_url` filter to generate the correct CDN URL with cache busting:
+
+```liquid
+<!-- Stylesheet -->
+<link rel="stylesheet" href="{{ 'main.css' | asset_url }}">
+```
+**Output:** `<link rel="stylesheet" href="https://cdn.example.com/assets/main-585919664682927.css">`
+
+```liquid
+<!-- JavaScript -->
+<script src="{{ 'cart.js' | asset_url }}" defer></script>
+```
+**Output:** `<script src="https://cdn.example.com/assets/cart-123456789.js" defer></script>`
+
+```liquid
+<!-- Image -->
+<img src="{{ 'logo.png' | asset_url }}" alt="Store Logo">
+```
+**Output:** `<img src="https://cdn.example.com/assets/logo-987654321.png" alt="Store Logo">`
+
+> **Important:** Pass only the filename to `asset_url` (e.g., `'main.css'`), not the full path. The filter prepends the CDN URL and uses `fingerprint.json` for cache-busted versioning.
+
+---
+
+## fingerprint.json
+
+This file maps original filenames to their cache-busted versions:
+
+```json
+{
+  "main.css": "main-585919664682927.css",
+  "header.js": "header-317103717237078.js",
+  "logo.png": "logo-442891003756812.png"
+}
+```
+
+When you use `{{ 'main.css' | asset_url }}`, Zoho Commerce looks up the fingerprinted filename and prepends the CDN URL. This ensures browsers always load the latest version after deployments.
+
+**Generating fingerprint.json:**
+
+Use the `create-theme` package to generate fingerprints and package your theme:
+
+```bash
+npx create-theme
+```
+
+This command minifies CSS/JS, fingerprints your assets, validates your code, and creates a deployment-ready `theme.zip`.
+
+---
+
+## Supported File Types
+
+| Type | Extensions | Notes |
+|------|-----------|-------|
+| Stylesheets | `.css` | Minify for production |
+| Scripts | `.js` | Use `defer` or `async` attributes |
+| Images | `.png`, `.jpg`, `.svg`, `.webp` | Optimize before uploading |
+| Fonts | `.woff`, `.woff2`, `.ttf` | Prefer `.woff2` for best compression |
+| Data | `.json` | Configuration or structured data |
+
+---
+
+## Using Images in Settings
+
+When using `image_picker` in section schemas, use just the filename for default values:
+
+```json
+{
+  "type": "image_picker",
+  "id": "banner_image",
+  "label": "Banner Image",
+  "default": {
+    "url": "banner_placeholder.webp",
+    "enable_customisation": true
+  }
+}
+```
+
+In your template, the URL may be either:
+- A filename (for theme defaults): `"banner_placeholder.webp"`
+- A full CDN URL (when admin uploads custom image): `"https://cdn.example.com/uploads/custom-banner.jpg"`
+
+Handle both cases appropriately in your Liquid code.
+
+---
+
+## Best Practices
+
+- **Use `asset_url` for every theme static file** — never hardcode paths
+- **Pass only filenames** to `asset_url`, not full paths like `/assets/main.css`
+- **Optimize images** before adding them to the assets folder
+- **Minify CSS and JS** for faster page loads (handled automatically by `npx create-theme` during build)
+- **Use descriptive filenames** — `product-gallery.js` not `pg.js`
+- **Run `npx create-theme`** before deploying to update fingerprints

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/best-practices.md

@@ -0,0 +1,212 @@
+---
+title: "Best Practices"
+weight: 15
+---
+
+# Best Practices
+
+Guidelines for building performant, secure, and maintainable Zoho Commerce themes.
+
+---
+
+## Performance
+
+### Minimize Asset Size
+
+- Minify CSS and JavaScript before deploying (handled automatically by `npx create-theme` during build)
+- Compress images (use WebP where supported)
+- Prefer `.woff2` fonts over `.ttf` or `.otf`
+
+### Optimize Loading
+
+```liquid
+<!-- Defer non-critical JavaScript -->
+<script src="{{ 'main.js' | asset_url }}" defer></script>
+
+<!-- Use async for independent scripts -->
+<script src="{{ 'analytics.js' | asset_url }}" async></script>
+
+<!-- Preload critical assets -->
+<link rel="preload" href="{{ 'main.css' | asset_url }}" as="style">
+```
+
+### Reduce Liquid Processing
+
+```liquid
+<!-- GOOD: Assign once, use many times -->
+{% assign formatted_title = product.title | upcase | truncate: 50 %}
+<span>{{ formatted_title }}</span>
+<meta content="{{ formatted_title }}">
+
+<!-- AVOID: Repeating the same filter chain -->
+<span>{{ product.title | upcase | truncate: 50 }}</span>
+<meta content="{{ product.title | upcase | truncate: 50 }}">
+```
+
+### Limit Loop Output
+
+```liquid
+<!-- Limit collection loops to prevent slow pages -->
+{% for product in collection.products limit: 12 %}
+  {% render 'product-card', product: product %}
+{% endfor %}
+```
+
+---
+
+## Security
+
+### Escape User Content
+
+Always escape output that may contain user-generated content:
+
+```liquid
+<!-- Escape text output -->
+{{ customer.first_name | escape }}
+{{ product.description | strip_html }}
+
+<!-- Safe for attribute values -->
+<div title="{{ product.title | escape }}">
+```
+
+### Avoid Inline Scripts from Settings
+
+```liquid
+<!-- AVOID: Injecting settings directly into script -->
+<script>var x = {{ section.settings.value }};</script>
+
+<!-- BETTER: Use data attributes -->
+<div data-value="{{ section.settings.value | escape }}"></div>
+<script>
+  var x = document.querySelector('[data-value]').dataset.value;
+</script>
+```
+
+### Use json Filter for Data
+
+```liquid
+<!-- Safe way to pass Liquid data to JavaScript -->
+<script>
+  var product = {{ product | json }};
+</script>
+```
+
+---
+
+## Accessibility
+
+### Semantic HTML
+
+```liquid
+<!-- Use proper heading hierarchy -->
+<h1>{{ page_title }}</h1>
+<h2>{{ section.settings.title }}</h2>
+
+<!-- Use semantic elements -->
+<nav>{% render 'navigation' %}</nav>
+<main>{{ content_for_layout }}</main>
+<footer>{% render 'footer' %}</footer>
+```
+
+### Image Alt Text
+
+```liquid
+<!-- Always provide alt text -->
+{{ product.cover_media | image_tag: alt: product.title }}
+
+<!-- Handle missing alt text -->
+{% assign alt = product.cover_media.alt | default: product.title %}
+<img src="{{ product.cover_media | image_url }}" alt="{{ alt }}">
+```
+
+### Form Labels
+
+```liquid
+<label for="email">{{ "form.email" | t }}</label>
+<input type="email" id="email" name="email" required>
+```
+
+---
+
+### Use Snippets for Reuse
+
+Extract repeated markup into snippets:
+
+```liquid
+<!-- Instead of duplicating product card markup in 5 sections -->
+{% render 'product-card', product: product, show_price: true %}
+```
+
+### Consistent Naming
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Files | lowercase, hyphens | `product-card.liquid` |
+| Setting IDs | snake_case | `button_color` |
+| CSS classes | lowercase, hyphens | `product-card--featured` |
+| Variables | snake_case | `sale_price` |
+| Translation keys | dot-separated | `product.add_to_cart` |
+
+### Schema Best Practices
+
+- Always set a `default` value for every setting
+- Use translation keys (`t:`) for labels in multi-language themes
+- Group related settings logically
+- Keep sections under 300 lines — split large sections into snippets
+
+---
+
+## Theme Editor UX
+
+### Provide Sensible Defaults
+
+Every section should look good out of the box:
+
+```json
+{
+  "type": "text",
+  "id": "title",
+  "label": "Heading",
+  "default": "Featured Products"
+}
+```
+
+### Use Conditional Visibility
+
+Hide irrelevant settings based on other setting values:
+
+```json
+{
+  "type": "text",
+  "id": "button_text",
+  "label": "Button Text",
+  "default": "Learn More",
+  "visible_if": "{{ show_button }}"
+}
+```
+
+### Order Settings Logically
+
+Place the most important settings first (title, content) and styling options last (colors, spacing).
+
+---
+
+## Deployment Checklist
+
+Before uploading your theme, verify the items below. Items marked with **auto** are automatically handled by `npx @zohofinance/commerce theme build` — you don't need to do them manually.
+
+**You need to verify:**
+- [ ] All settings have default values
+- [ ] No hardcoded text — all strings use `t` filter
+- [ ] Images are compressed and optimized
+- [ ] Tested on mobile and desktop
+- [ ] All sections render correctly in the theme editor
+- [ ] Translation files cover all locales
+
+**Handled automatically by the CLI build:**
+- [ ] `fingerprint.json` is generated correctly *(auto)*
+- [ ] CSS and JS are minified *(auto — with `--prod`)*
+- [ ] Liquid, JS and asset files are validated *(auto)*
+- [ ] No broken asset references *(auto)*
+
+> Run `npx @zohofinance/commerce theme build --prod` and it takes care of all the auto items above — fingerprinting, minification, Brotli compression, and full validation in one step.