@zohofinance/commerce 1.0.0 → 1.0.1

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

@@ -0,0 +1,199 @@
+# Level A — Page orchestrator (identifies sections, spawns Level B)
+
+One Level A agent per page. **Does not write section Liquid.** Identifies sections from the page Figma frame, spawns **Level B** (section builder) per section in parallel, assembles `pages/<page>.json`, runs whole-page visual verify.
+
+See `agent-hierarchy.md`.
+
+Five page orchestrators run (Stage 1a + Stage 1b). The common-pages orchestrator (Stage 1c) follows the same pattern for cart/checkout/account.
+
+## Read first
+
+- `dev-server-and-urls.md` — confirmed storeUrl + page URLs before browser verify.
+- `subagent-escalation.md` — escalate all blockers/questions to main agent screen.
+- `zcommerce-docs/pages.md` — page JSON contract (section order, settings shape).
+- `zcommerce-docs/sections.md` — section structure (because you'll be giving subagents specs).
+- `section-builder.md` — what the subagents you spawn will do.
+- `ask-developer.md` — when to surface ambiguity to the developer vs decide.
+
+## Inputs
+
+From the main orchestrator:
+- Page name and Figma URL(s) (desktop + mobile).
+- Theme folder path.
+- Scratchpad path at `.claude/scratchpad/<theme>/pages/<page>/`.
+- Locked files: `theme.json`, `tailwind.config.js`, `figma-variables.json`.
+- For page agents other than `index`: wait for `header-footer-ready` marker before starting verification.
+
+## Workflow
+
+### Phase 1 — Page intake (~45s)
+
+Pull from Figma in parallel:
+- `get_screenshot` desktop frame
+- `get_screenshot` mobile frame
+- `get_design_context` desktop frame
+- `get_design_context` mobile frame
+
+Save raw artefacts to scratchpad. **Do not** start identifying sections from the screenshot alone — use `get_design_context` to get the structured node tree which tells you the real boundaries.
+
+### Phase 2 — Section identification (~30s)
+
+Walk the design context top to bottom. Identify distinct sections by:
+- Top-level frame children that look like full-width content blocks
+- Visual whitespace breaks between groups of elements
+- Repeated patterns (3 cards → likely one "card grid" section, not 3 sections)
+
+Produce a section plan:
+
+```
+SECTION 1  header             (top region, frame node 1234:5)
+SECTION 2  hero-banner        (full-width banner, node 1234:8)
+SECTION 3  feature-row        (3-column feature highlights, node 1234:12)
+SECTION 4  featured-products  (product grid, node 1234:20)
+SECTION 5  cta-banner         (single CTA strip, node 1234:30)
+SECTION 6  newsletter-signup  (form + heading, node 1234:35)
+SECTION 7  footer             (bottom region, node 1234:40)
+```
+
+For each, record:
+- Section name (snake-case, used as filename)
+- Figma node ID (for the section subagent's `get_screenshot` crop)
+- Archetype (hero, product-grid, etc. — for exemplar lookup)
+- Estimated complexity (small / medium / large — for time budgeting)
+
+**Ambiguity check:** If a region's identity is unclear (two adjacent banners — is it one section with 2 blocks or 2 separate sections?), add it to the `pending_questions.md` file in scratchpad. Don't decide yet.
+
+**Hard rule — the section list matches the Figma 1:1.** Every section in `sections.plan.md` must correspond to a region visible in the Figma frame. Do NOT include sections you "think would be useful" or "are pre-existing in sibling themes" if they aren't shown in the Figma. The bug that shipped in a prior build (a "Why families pick us" / value-props block appearing on the rendered page despite not being in the Figma) was caused by the agent including a section from its memory of sibling themes rather than from the Figma. The plan must be visually grounded in the Figma frame — no inventions, no carryovers.
+
+If a section type seems useful but isn't in the Figma, write a NEEDS_REVIEW item explaining what's missing. Let the developer decide. Don't add silently.
+
+### Phase 3 — Snippet planning (~1min)
+
+Identify shared snippets needed across multiple sections on this page:
+- `product-card` — used by listing and featured-products
+- `cart-row` — used by cart-list and cart-popup
+- `pagination` — used by listing and blog-list
+- `pricing-display` — used by product-card and product-details
+
+For each shared snippet, build FRESH from the docs (`zcommerce-docs/snippets.md`) using the theme tokens. Save to `snippets/<name>.liquid`.
+
+Run lint on each snippet before continuing. Snippets must pass lint just like sections.
+
+Record the snippet registry in `<scratchpad>/snippets.md`:
+```
+- product-card.liquid (params: product, show_price=true) — usable by hero, featured-products, listing
+- pricing-display.liquid (params: price, compare_at_price) — usable by product-card, product-details
+- pagination.liquid (params: paginate_obj) — usable by listing, blog-list
+```
+
+This registry is passed to every section subagent. Subagents render existing snippets via `{% render '<name>' %}`; they do NOT redefine.
+
+### Phase 4 — Spawn Level B subagents (PARALLEL)
+
+One subagent per section. **Level A must not build sections itself.**
+
+Send N `Task` / `Agent` calls in one message. Each prompt MUST state:
+
+```
+You are LEVEL B — section builder.
+Scope: section "<section_name>" ONLY. Figma node: <desktop_node_id>.
+Do NOT call get_design_context on the parent page frame.
+Follow: section-builder.md, figma-extraction.md, transcription-rules.md.
+Verify: lint-section.mjs + Chrome DevTools visual vs section Figma crop.
+PASS = visual-diff.md with 0 CRITICAL.
+```
+
+Pass to each Level B:
+- `section_name`, `figma_node_id` (desktop + mobile if different)
+- `scratchpad` path: `pages/<page>/sections/<section_name>/`
+- `page_url` from `dev-config.json` (for browser verify scroll target)
+- `snippets.md` registry (render only, do not redefine)
+- Lock: other sections' files, theme.json, figma-variables.json
+
+### Phase 5 — Wait + collect (varies, ~3-5min)
+
+Wait for all section subagents to finish. Each writes a report to `<scratchpad>/sections/<name>/report.md` with:
+- Verdict (PASS / FAIL / NEEDS_REVIEW)
+- Lint results
+- Per-section pixel-diff result (vs the section's Figma crop)
+- Per-section axe result
+- List of unresolved questions for the developer (if any)
+
+### Phase 6 — Batch developer questions (one round)
+
+Collect all `pending_questions.md` files (from phase 2) + `unresolved.md` from each section subagent.
+
+If there are questions, present them as ONE batched `AskUserQuestion` call. Group similar questions. Cap at 4 questions per batch (AskUserQuestion's limit); if more, ask the most consequential 4 and defer the rest with sensible defaults logged in NEEDS_REVIEW.
+
+After the developer answers, propagate answers to the affected section subagents OR (if they've already finished) edit the produced files directly and re-run gates.
+
+### Phase 7 — Assemble page JSON (~30s)
+
+Write `pages/<page>.json` with the section order from phase 2 and each section's default settings.
+
+**Hard rule — populate every multi-block section's blocks with distinct, Figma-transcribed content.** For sections that have multiple block instances of the same type (e.g., a blog-highlights section with `post_1`, `post_2`, `post_3` blocks), the page JSON must transcribe each block's specific content from the Figma:
+
+- Each block's `settings` object must be non-empty (not `{}`).
+- Each block's settings must be distinct from sibling blocks of the same type — no two blocks with byte-identical settings unless the Figma actually shows duplicates.
+- Headlines, body copy, image filenames, dates, button labels, link handles — all from the Figma frame for that specific card, NOT inherited from the schema's `default` field.
+
+Why this matters: schema defaults are fallbacks for when the customizer admin clears a value. They're not intended to fill multiple blocks with the same content. If the agent leaves `settings: {}` for `post_2` and `post_3`, all three cards render the schema's `post_title` default identically — the bug that shipped in a prior build. `verify-theme.mjs`'s `block_settings_populated` check catches this.
+
+For the listing agent: also write `pages/collection.json`, `pages/category.json`, `pages/search.json` (all relative to the theme root) — all three use the same sections.
+
+### Phase 8 — WHOLE-PAGE verification via Chrome DevTools MCP (~2min)
+
+Section subagents verified their pieces. The page orchestrator verifies the **assembled whole** using the same 3-gate workflow (see `visual-verify-loop.md` §Per-page loop):
+
+1. `emulate` desktop 1440×900 → `navigate_page` → full-page `take_screenshot`
+2. `emulate` mobile 375×812 → `take_screenshot`
+3. Figma `get_screenshot` on page-level desktop + mobile node IDs
+4. Agent vision → `pages/<page>/visual-diff.md` (focus: section order, gaps, missing/extra blocks)
+5. `lighthouse_audit` navigation mobile — a11y ≥ 90, perf ≥ 85
+6. `list_console_messages` + `list_network_requests`
+
+**PASS:** 0 CRITICAL in page `visual-diff.md`.
+
+**If sections passed but page fails:** fix inter-section spacing/order in `pages/<page>.json` or offending section padding. Max **2 iterations**.
+
+Optional: run `pixel-diff.mjs` for CI JSON artefacts — not required when MCP visual compare passes.
+
+### Phase 9 — Report + escalate to main agent
+
+Write final page report to `<scratchpad>/pages/<page>/report.md`.
+
+Include an **ESCALATION** block (see `subagent-escalation.md`) in the return message so the main orchestrator posts it to the developer chat — even if you already used `AskUserQuestion` during the build.
+
+```
+PAGE: index
+SECTIONS BUILT: 7
+SHARED SNIPPETS BUILT: 2 (product-card, pricing-display)
+
+PER-SECTION VERIFY (all PASS):
+  header                pixel-diff 1.2 / a11y pass / lint pass
+  hero-banner           pixel-diff 1.8 / a11y pass / lint pass
+  feature-row           pixel-diff 1.4 / a11y pass / lint pass
+  featured-products     pixel-diff 2.1 / a11y pass / lint pass (1 iteration)
+  cta-banner            pixel-diff 1.6 / a11y pass / lint pass
+  newsletter-signup     pixel-diff 1.9 / a11y pass / lint pass
+  footer                pixel-diff 1.5 / a11y pass / lint pass
+
+WHOLE-PAGE VERIFY:
+  desktop pixel-diff    mean 1.7, max 4.2 — PASS
+  mobile pixel-diff     mean 2.0, max 5.8 — PASS
+  axe                   0 critical, 0 serious, 1 moderate
+  lighthouse mobile     perf 93, LCP 1.9s, CLS 0.02
+
+DEVELOPER QUESTIONS ASKED: 2 (frame mapping for feature-row, hover color for CTA)
+ITERATIONS: 1 (featured-products padding)
+NEEDS_REVIEW: 0
+```
+
+## Things to NOT do
+
+- Don't build sections yourself — that's the subagents' job.
+- Don't approve a page where section-level verify passed but whole-page failed without iterating.
+- Don't ask the developer per-section — batch at phase 6.
+- Don't skip whole-page verify even if every section passed individually.
+- Don't write shared snippets after spawning subagents — that creates race conditions. Write them in phase 3.
+- Don't modify locked files (theme.json, etc., or other sections' files).

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

@@ -0,0 +1,152 @@
+# Stage 1 — Level A fan-out (page orchestrators)
+
+Stage 1 uses the **Level 0 → A → B** hierarchy from `agent-hierarchy.md`.
+
+- **Level 0** spawns **Level A** agents (one per page).
+- **Level A** spawns **Level B** agents (one per section on that page).
+- **Level B** builds and verifies sections — Level A never writes section Liquid.
+
+---
+
+## Phase 1a — Index Level A (serial, ~4–6 min)
+
+The index Level A runs **first and alone**. It identifies sections on the home page, spawns Level B for header + footer + all index sections, assembles `pages/index.json`, and publishes the `header-footer-ready` marker.
+
+```
+Phase 1a:  Level A (index)  →  Level B × N sections  ────████████████ ~4–6min
+```
+
+**Spawn one Level A agent:**
+
+- **`subagent_type`**: `generalPurpose`
+- **`description`**: `Level A: index page`
+- **`prompt`**: see template below with `PAGE_NAME=index`
+
+After index Level A finishes and writes `.claude/scratchpad/<theme>/header-footer-ready`, proceed to Phase 1b.
+
+---
+
+## Phase 1b — Four parallel Level A agents (~4–6 min)
+
+Spawn four Level A agents in one message (concurrent):
+
+| Level A agent | Page | Page JSON |
+|---|---|---|
+| listing | `listing` | `collection.json`, `category.json`, `search.json` |
+| product | `product` | `product.json` |
+| blog_list | `blog_list` | `blogs.json` |
+| blog_detail | `blog_detail` | `blog.json` |
+
+Each Level A:
+1. Identifies sections → `sections.plan.md`
+2. Spawns Level B per section (parallel)
+3. Assembles page JSON
+4. Whole-page visual verify vs Figma page frame
+
+```
+Phase 1b:                    listing   ─────────────████████ ~4min
+                             product   ─────────────██████████ ~5min
+                             blog_list ─────────────████ ~3min
+                             blog_detail ───────────████ ~3min
+```
+
+Wall-clock ≈ slowest Level A agent (~5–7 min after index).
+
+---
+
+## Level A spawn template
+
+```
+You are LEVEL A — page orchestrator for the <PAGE_NAME> page.
+You do NOT write section Liquid. You identify sections and spawn Level B agents.
+
+THEME: <theme_name>
+THEME FOLDER: <theme_name>/
+SCRATCHPAD: .claude/scratchpad/<theme_name>/pages/<page_name>/
+FIGMA: desktop node <desktop_node_id>, mobile node <mobile_node_id>
+PAGE URL: read from .claude/scratchpad/<theme>/dev-config.json — never guess
+
+WORKFLOW: Follow page-orchestrator.md exactly.
+HIERARCHY: agent-hierarchy.md — scope = page frame for identification only.
+SECTION SPAWN: For each section in sections.plan.md, spawn one Level B agent
+  (see Level B template below). All Level B in one parallel message.
+
+LOCKED (do not modify):
+- settings/theme.json, tailwind.config.js, figma-variables.json
+- header.liquid, footer.liquid (after header-footer-ready marker exists)
+
+OUTPUT:
+- sections.plan.md (section list + Figma node IDs)
+- pages/<page_json>.json assembled after all Level B PASS
+- report.md with whole-page visual verify result
+- ESCALATION block per subagent-escalation.md
+
+Return summary + ESCALATION block. Main agent surfaces questions on screen.
+```
+
+---
+
+## Level B spawn template (used BY Level A, not Level 0)
+
+Level A sends N `Task` calls in one message — one per section:
+
+```
+You are LEVEL B — section builder.
+Scope: section "<section_name>" ONLY.
+Figma node: <desktop_node_id> (mobile: <mobile_node_id> if different).
+
+Do NOT call get_design_context on the parent page frame.
+Do NOT read other sections' Figma or Liquid files for visual values.
+
+THEME FOLDER: <theme_name>/
+SCRATCHPAD: .claude/scratchpad/<theme_name>/pages/<page_name>/sections/<section_name>/
+PAGE URL: <from dev-config.json> — scroll to this section for browser verify
+
+WORKFLOW: section-builder.md, figma-extraction.md, transcription-rules.md
+VERIFY:
+  1. lint-section.mjs PASS (syntax / docs)
+  2. Chrome DevTools visual vs Figma SECTION crop
+  3. visual-diff.md with 0 CRITICAL
+
+LOCKED: all other sections/*.liquid, theme.json, figma-variables.json
+
+Return PASS/FAIL + ESCALATION block.
+```
+
+---
+
+## Coordination rules
+
+1. **One section file = one Level B agent.** No two agents write the same `.liquid`.
+2. **Level A never builds sections.** If tempted to "quickly fix" a section, re-spawn Level B.
+3. **Level B scope = one Figma section node.** Prevents border-radius/color/card-height hallucination.
+4. **i18n append-only** with section-scoped keys: `sections.<section_name>.*`
+5. **Locked files** — see `agent-hierarchy.md` scope table.
+6. **Scratchpad isolation** — Level B writes to `pages/<page>/sections/<section>/`
+
+---
+
+## Race detection (after all Level A finish)
+
+Confirm:
+- Each `sections/*.liquid` touched by exactly one Level B
+- Each Level B wrote `figma-spec.json` + `visual-diff.md`
+- Each Level A wrote `sections.plan.md` + `report.md`
+- No Level A/B modified locked files
+- `header-footer-ready` exists before non-index Level A started
+
+If any fail → stop before Stage 2.
+
+---
+
+## When NOT to fan out
+
+- Single-page iteration after initial build — run one Level A directly.
+- Previous fan-out failed mid-flight — investigate before retry.
+- Theme has < 3 pages — overhead may not be worth it.
+
+---
+
+## Deprecated
+
+`page-builder.md` described the old flat page-agent model (one agent builds entire page). **Do not use.** Use `page-orchestrator.md` (Level A) + `section-builder.md` (Level B).

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/scripts/a11y.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * a11y.mjs — run axe-core (WCAG 2.1 AA) against a URL via headless Chrome.
+ *
+ * Usage:
+ *   node a11y.mjs \
+ *     --url       http://localhost:3000/home \
+ *     --selector  "#section-hero"     (optional — scope axe to one section)
+ *     --out       /path/to/axe.json
+ *
+ * Output JSON shape:
+ *   {
+ *     "url": "...",
+ *     "selector": null | "...",
+ *     "tags": ["wcag2a","wcag2aa","wcag21a","wcag21aa"],
+ *     "summary": {
+ *       "critical": 0, "serious": 1, "moderate": 2, "minor": 1
+ *     },
+ *     "violations": [
+ *       { "id":"color-contrast", "impact":"serious", "nodes":[...], "help":"..." },
+ *       ...
+ *     ],
+ *     "verdict": "PASS" | "FAIL"
+ *   }
+ *
+ * Pass threshold: zero critical AND zero serious violations.
+ *
+ * Dependencies: puppeteer, axe-core
+ *   npm install --no-save puppeteer axe-core
+ *   (reuse this theme's node_modules if axe-core is already installed.)
+ */
+
+import puppeteer from 'puppeteer';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+
+const args = parseArgs(process.argv.slice(2));
+const url = required(args, 'url');
+const selector = args.selector || null;
+const outPath = required(args, 'out');
+
+const axeCorePath = (() => {
+  const candidates = [
+    'axe-core',
+    path.resolve(process.cwd(), 'node_modules/axe-core'),
+  ];
+  for (const c of candidates) {
+    try { return require.resolve(`${c}/axe.min.js`); } catch {}
+  }
+  fail('Could not locate axe-core. Run: npm install --no-save axe-core');
+})();
+
+(async () => {
+  const browser = await puppeteer.launch({
+    headless: 'new',
+    args: ['--no-sandbox', '--disable-setuid-sandbox'],
+  });
+  try {
+    const page = await browser.newPage();
+    await page.goto(url, { waitUntil: 'networkidle2', timeout: 60_000 });
+    await page.addScriptTag({ path: axeCorePath });
+
+    const results = await page.evaluate(async (scopeSelector) => {
+      const opts = {
+        runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'] },
+        resultTypes: ['violations'],
+      };
+      const context = scopeSelector ? document.querySelector(scopeSelector) : document;
+      if (scopeSelector && !context) {
+        return { error: `Selector not found: ${scopeSelector}` };
+      }
+      // eslint-disable-next-line no-undef
+      return await axe.run(context, opts);
+    }, selector);
+
+    if (results?.error) fail(results.error);
+
+    const violations = (results.violations || []).map((v) => ({
+      id: v.id,
+      impact: v.impact,
+      help: v.help,
+      help_url: v.helpUrl,
+      tags: v.tags,
+      node_count: v.nodes.length,
+      sample_nodes: v.nodes.slice(0, 5).map((n) => ({
+        target: n.target,
+        html: n.html,
+        failure_summary: n.failureSummary,
+      })),
+    }));
+
+    const summary = { critical: 0, serious: 0, moderate: 0, minor: 0 };
+    for (const v of violations) summary[v.impact] = (summary[v.impact] ?? 0) + v.node_count;
+
+    const verdict = summary.critical === 0 && summary.serious === 0 ? 'PASS' : 'FAIL';
+
+    const report = {
+      url,
+      selector,
+      tags: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'],
+      summary,
+      violations,
+      verdict,
+    };
+
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, JSON.stringify(report, null, 2));
+    console.log(JSON.stringify(report, null, 2));
+  } finally {
+    await browser.close();
+  }
+})().catch((e) => fail(e.message ?? String(e)));
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) {
+      const key = argv[i].slice(2);
+      const val = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : 'true';
+      out[key] = val;
+    }
+  }
+  return out;
+}
+function required(args, k) { if (!args[k]) fail(`Missing --${k}`); return args[k]; }
+function fail(msg) { console.error('a11y error:', msg); process.exit(2); }